Skip to content

Javadoc for Document Context Handling #1030

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: adv/docs
Choose a base branch
from

Conversation

peter-lawrey
Copy link
Member

@peter-lawrey peter-lawrey commented May 30, 2025

✨ What’s new in this PR

A focused documentation pass over Chronicle Wire’s document-context stack plus one tiny API convenience method.

  • Brand-new DocumentContext#isOpen() default method
     – a friendly alias that mirrors isNotComplete() and reads more intuitively in client code.

  • Thorough, consistent Javadoc across the read/write context family
    (DocumentContext, WriteDocumentContext, ReadDocumentContext,
    Text*DocumentContext, Binary*DocumentContext,
    DocumentContextHolder, WrappedDocumentContext,
    NoDocumentContext, DocumentWritten).

    • first-line “intent sentences” for IDE tooltips
    • clarified life-cycle rules (start/close/reset, rollback, chaining)
    • examples, parameter/return semantics, exception notes
    • internal field explanations and threading notes
    • removal of stale references (delta wire, obsolete flags)
  • No behavioural changes – only comments and the small, backwards-compatible addition of isOpen().


Commit guide

Commit Message Highlights
01/10 Create the branch Adds isOpen() (defaults to isNotComplete()) + stub Javadoc.
02/10 Improve DocumentContext Javadoc (#1021) Full rewrite; examples & contract clarifications.
03/10 Improve WriteDocumentContext Javadoc (#1022) Adds start/chain semantics, empty-check docs.
04/10 Clarify ReadDocumentContext behaviour (#1023) Documents limit/position restore helpers.
05/10 Improve TextReadDocumentContext Javadoc (#1024) Explains ---/… parsing helpers.
06/10 Improve TextWriteDocumentContext Javadoc (#1025) Details separator handling, rollback flow.
07/10 Improve BinaryReadDocumentContext Javadoc (#1026) Modern docs + deprecation note on delta wire.
08/10 Improve BinaryWriteDocumentContext Javadoc (#1027) Header-writing algorithm spelled out.
09/10 Improve context holder Javadocs (#1028) Docs for wrapper classes & DocumentWritten.
10/10 Improve Javadoc for context wrappers (#1029) Final tidy-up (NoDocumentContext, WrappedDocumentContext).

@peter-lawrey peter-lawrey changed the base branch from ea to adv/docs May 30, 2025 11:45
@peter-lawrey peter-lawrey force-pushed the adv/02-document-context branch from 7cb3226 to 2cb1906 Compare June 2, 2025 09:21
@peter-lawrey peter-lawrey requested a review from tgd June 3, 2025 11:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant