Claude_prompt_doc.txt

==============================================================================================================================================

------
Use multiple agents to perform a thorough deep line by line review for javadocs in all the classes under folder: ./src/main/java to improve/correct existing javadocs

------
Use multiple agents to perform a thorough deep line by line review for javadocs in all the classes in packages: com.landawn.abacus.util under: ./src/main/java to improve/correct existing javadocs


------
TASK: Start multiple agents to generate comprehensive Javadoc for all public methods, including public static methods but skip the methods annotated with @Override, in all classes and interfaces under folder: ./src/main/java/. The Javadoc should be detailed and precise, thoroughly explaining the method’s purpose, behavior, parameters, return value, and exceptions. Document the CONTRACT, not the implementation: what it does, not how. Where applicable, include a concise usage example (a couple of lines). The example block should always be placed before any @param, @return, or other annotation tags. If Javadoc already exists, review it against the actual implementation and update it for accuracy and clarity. Finally, merge the new or revised Javadoc directly into source file, replacing any existing documentation. DON'T skip any class. For methods annotated with @Override, just review, improve and verify existing javadoc for them. Don't add or generate new javadoc for methods annotated with @Override. Use below template for usage example in Javadoc:

       * Description of what the method does.
       *
       * <p><b>Usage Examples:</b></p>
       * <pre>{@code
       * ClassName.method("x");      // returns ...
       * ClassName.method(null);     // throws NullPointerException
       * }</pre>
       *
       * @param ...


------
   Task: Review and improve Javadoc. Add documentation to undocumented members only; do not change any executable
   code.

   Principle: Document the contract, not the implementation. Describe what a member does and the guarantees it
   makes (inputs, outputs, preconditions, side effects, thread-safety, nullability) — not how it does it
   internally.

   Review each member against the following criteria:

   1. Accuracy — The prose must correctly describe actual behavior. Verify:
       • @param names and descriptions match the real method signature; flag missing, extra, or misnamed tags.
       • @return is present on non-void methods and absent on void/constructors.
       • @throws/@exception documents every checked exception thrown, with correct trigger conditions; flag
         undocumented or incorrectly documented throws.
       • {@link} and @see references resolve and point to the right targets.
       • Flag stale, copy-pasted, contradictory, or simply wrong descriptions.

   2. Clarity — Wording must be unambiguous, grammatically correct, and complete. Flag confusing phrasing, typos,
      incomplete sentences, and vacuous descriptions that merely restate the method name without adding
      information.

   3. Consistency — Terminology, phrasing, tag ordering, and formatting should be uniform across the codebase.
      Cross-variant consistency matters most: this code is largely template-generated, so analogous members across
      sibling classes (e.g. CharTuple vs. LongTuple, primitive-type variants, arity variants) must document the
      same concept with the same wording. Flag any variant whose Javadoc diverges from its siblings.

   4. Code samples — Any <pre>{@code ...} example in the Javadoc must be correct and compilable in principle (valid
      syntax, right method names/signatures, accurate output), and must demonstrate idiomatic usage that reflects
      the intended design. Flag samples that are wrong, misleading, or show poor practice.




==============================================================================================================================================


------

Begin the task below by leveraging the existing Python scripts under ./scripts/. If completing the task requires modifying any script, include a complete account of every change (which script, what changed, and why) in your final summary.

  TASK: Start multiple agents to audit and complete the Javadoc “Usage Examples” for public methods in public classes under ./src/main/java/.

  This is a COMMENTS-ONLY task.
  Do not change method logic, signatures, imports, annotations, formatting outside comments, or any non-comment code.

  Scope:
  - Include public methods in public top-level classes and nested public classes.
  - Only modify methods that already have a Javadoc comment.
  - Ignore public methods annotated with @Override
  - Do not add Javadocs to undocumented methods.
  - Do not modify Javadoc or code that is commented out with //.
  - Do not remove sample-code comments that start with //.

  =======================================================================
  1. GOAL PER PUBLIC METHOD
  =======================================================================

  For each in-scope public method with existing Javadoc:

  1. If it has no Usage Examples block:
     Add one with at least:
     - 2 basic or typical examples
     - 2 edge, negative, or boundary examples, as applicable:
       null, empty, blank, min/max boundary, overflow, exception, NaN, Infinity, etc.

  2. If it already has examples:
     Audit every example line against actual library behavior.
     Fix incorrect return values, exception comments, mutation descriptions, or misleading explanations.

  3. Make examples meaningful:
     Existing examples that are technically correct but redundant, shallow, or missing common usage should be improved or supplemented.

  4. Checked exceptions:
     Document checked exceptions with a trailing comment:
     // throws IOException

  5. Library behavior is the ground truth:
     Never guess expected values. Verify with tests.

  =======================================================================
  2. REQUIRED JAVADOC STYLE
  =======================================================================

  Place the Usage Examples block after the method description and before all Javadoc tags.

  Required order:

  description
  blank Javadoc line
  Usage Examples block
  blank Javadoc line
  @param / @return / @throws / @see / @since / @deprecated tags

  Example:

       * Description of what the method does.
       *
       * <p><b>Usage Examples:</b></p>
       * <pre>{@code
       * ClassName.method("x");      // returns ...
       * ClassName.method(null);     // throws NullPointerException
       * }</pre>
       *
       * @param ...

  Rules:
  - Use exactly one blank Javadoc line before and after the Usage Examples block.
  - A blank Javadoc line must contain only the standard prefix, for example:
        *
  - Every example line must be a real, compilable call or setup statement.
  - Every behavior example must include a // returns, // throws, or equivalent post-state comment.
  - Declare helper variables inside the <pre>{@code} block so examples are self-contained.
  - If an existing examples header has custom wording, keep that wording but bold it:
    <p><b>Example usage with a mutable counter:</b></p>
  - Do not replace meaningful custom headers with “Usage Examples”.

  =======================================================================
  3. COMMON PITFALLS
  =======================================================================

  Overload ambiguity:
  - Cast null, empty arrays, or ambiguous literals when needed:
    (String) null
    (Object) null
    (int[]) null

  Abacus optionals:
  - Use Abacus optional APIs:
    isPresent()
    get()
    getAsInt()
    getAsLong()
    getAsFloat()
    getAsDouble()
  - Do not use java.util.Optional accessors unless the method actually returns java.util.Optional.

  Floating-point values:
  - For NaN, verify with Double.isNaN(...) or Float.isNaN(...).
  - For infinity, compare to POSITIVE_INFINITY or NEGATIVE_INFINITY.

  Numeric and parsing behavior:
  - Verify hex, octal, NaN/Infinity rejection, result types, and index boundaries.
  - Do not infer behavior from method names.

  Mutation methods:
  - Document both the return value and the post-state mutation in the same example line where practical.

  Formatting:
  - Never produce this malformed line:
        *          * <p><b>Usage Examples:</b></p>
  - Correct:
        * <p><b>Usage Examples:</b></p>
  - Every @param, @return, and @throws line must keep the normal Javadoc prefix:
        * @param value description
  - Inner class Javadocs must use the same indentation as their surrounding tags.

  =======================================================================
  4. PROCESS
  =======================================================================

  Process classes in the order listed below. If multiple-agent tooling is available, agents may work in parallel, but each agent must handle only one class at a time.

  For each class:

  Step A: Build the public method list

  Use:

  grep -nE "^\s+public (static )?[A-Za-z].*\(" <Class.java>

  Then manually exclude out-of-scope items.

  Step B: Create a throwaway verification test

  Path:
  src/test/java/.../<ClassName>JavadocVerifyTest.java

  Guidelines:
  - Mirror imports and style from the existing <ClassName>Test.java when available.
  - If no existing test exists, mirror the package structure and imports needed by the source class.
  - Write one @Test per public method covered.
  - Every documented example must have a corresponding assertion.
  - Use real assertions:
    assertEquals
    assertArrayEquals
    assertThrows
    assertNull
    assertTrue

  Step C: Write or audit examples, then run the test

  Use:

  mvn -o test -Dtest=<ClassName>JavadocVerifyTest -Dmaven.main.skip=true

  Do not run mvn clean during this loop.

  Step D: Fix and repeat

  - If assertions fail, fix the Javadoc example and test expectation to match actual library behavior.
  - If examples do not compile, fix both the Javadoc and test.
  - Add casts where overload ambiguity occurs.
  - Repeat until the class verification test is green.

  Step E: Align Javadoc examples

  After the class verification test is green, run:

  python ./scripts/align_jdoc_examples.py --apply <RELATIVE/PATH/TO/Class.java>

  If the script is unavailable, manually align // comments consistently throughout the class.

  Step F: Delete the throwaway test

  After the class is green and alignment is complete, delete:

  src/test/java/.../<ClassName>JavadocVerifyTest.java

  =======================================================================
  5. CLASS ORDER
  =======================================================================

  Group 1:
  - Arrays.java

  Group 2:
  - All remaining in-scope classes

  =======================================================================
  6. PAUSE POINT
  =======================================================================

  After completing Arrays.java:
  - Stop.
  - Report the results.
  - Wait for review before proceeding to Group 2.

  =======================================================================
  7. FINAL VERIFICATION
  =======================================================================

  After all classes are complete, run:

  mvn -o compile

  The build must finish with BUILD SUCCESS.

  =======================================================================
  8. FINAL REPORT
  =======================================================================

  Report:
  - Classes processed: <count>
  - Public methods covered: <count>
  - Examples added: <count>
  - Examples fixed: <count>
  - Notable behavior corrections:
    method -> documented/wrong value -> actual/correct value
  - Confirm:
    - all throwaway tests deleted
    - alignment applied
    - final build green
    - only comments were edited



==============================================================================================================================================


------
Rewritten by Claude code:

TASK: Run agents to audit, format, and improve EXISTING Javadoc “Usage Examples”
blocks for public methods of public classes under ./src/main/java/.

This is a COMMENTS-ONLY task. Reuse the existing toolkit in ./scripts/codex/ —
do not re-implement scope detection, validation, or formatting that already exists
there. Read a script's header for its exact usage before running it.

=======================================================================
0. EXECUTION MODEL (phases)
=======================================================================
Phase 1 — Stream.java ONLY, handled by a SINGLE agent (it is one large file;
  parallel agents on one file collide on a comments-only diff). After Stream.java
  is green and validated, STOP and produce the change report (Section 6) for review.
Phase 2+ — only after approval: fan out with ONE FILE PER AGENT (never two agents
  in the same file). Each agent runs the full pipeline below on its file.

=======================================================================
1. SCOPE  (already encoded in scripts/codex/inventory_jdoc_usage_files.js)
=======================================================================
Process public methods in every public top-level class and every public nested class.

Use the inventory script to get the authoritative in-scope list (Stream.java is
opt-in by design — pass it explicitly):
  node scripts/codex/inventory_jdoc_usage_files.js src/main/java Stream.java

Only classes that ALREADY contain an example block are in scope. Do not add new
Javadoc and do not add a Usage Examples block where none exists.

=======================================================================
2. WHAT TO CHANGE (and what not to)
=======================================================================
Only edit existing Javadoc example/sample blocks. Do NOT change: method logic,
signatures, imports, annotations, non-comment code, or non-example Javadoc prose
— except the minimum needed to position/format an existing examples block.

For each existing examples block:
  a) AUDIT CORRECTNESS. Verify calls, comments, return values, side effects, and
     thrown exceptions against actual behavior. Inspect the implementation and
     nearby tests when unclear. Do not guess — if you cannot confirm, leave it and
     report it as an uncertainty.
  b) IMPROVE CONSERVATIVELY. Prefer minimal correctness fixes. Only restructure or
     replace an example when it is clearly redundant, shallow, or misleading.
     Replace `(...)` placeholders with concrete arguments when practical; if a
     placeholder cannot be replaced without guessing, leave it and report it.
  c) PRESERVE INTENT.
     - Keep meaningful custom headers; bold them, e.g.
       * <p><b>Example usage with a mutable counter:</b></p>
       Only replace a header with “Usage Examples:” if it is generic or malformed.
     - Do not touch Javadoc that is commented out with `//`.
     - Preserve standalone section-heading comments that organize a multi-part
Only classes that ALREADY contain an example block are in scope. Do not add new
Javadoc and do not add a Usage Examples block where none exists.

=======================================================================
2. WHAT TO CHANGE (and what not to)
=======================================================================
Only edit existing Javadoc example/sample blocks. Do NOT change: method logic,
signatures, imports, annotations, non-comment code, or non-example Javadoc prose
— except the minimum needed to position/format an existing examples block.

For each existing examples block:
  a) AUDIT CORRECTNESS. Verify calls, comments, return values, side effects, and
     thrown exceptions against actual behavior. Inspect the implementation and
     nearby tests when unclear. Do not guess — if you cannot confirm, leave it and
     report it as an uncertainty.
  b) IMPROVE CONSERVATIVELY. Prefer minimal correctness fixes. Only restructure or
     replace an example when it is clearly redundant, shallow, or misleading.
     Replace `(...)` placeholders with concrete arguments when practical; if a
     placeholder cannot be replaced without guessing, leave it and report it.
  c) PRESERVE INTENT.
     - Keep meaningful custom headers; bold them, e.g.
       * <p><b>Example usage with a mutable counter:</b></p>
       Only replace a header with “Usage Examples:” if it is generic or malformed.
     - Do not touch Javadoc that is commented out with `//`.
     - Preserve standalone section-heading comments that organize a multi-part
       example (title-case is fine here), e.g.  `* // Mathematical operations`.
       The lowercase/trailing-comment style rule applies to comments AFTER an
       executable sample line, not to section headings.

=======================================================================
3. REQUIRED STRUCTURE & FORMATTING
=======================================================================
Place the examples block AFTER the method description and BEFORE all tags
(@param, @return, @throws, @see, @since, @deprecated):

     * Description of what the method does.
     *
     * <p><b>Usage Examples:</b></p>
     * <pre>{@code
     * ClassName.method("x");      // common case
     * ClassName.method(null);     // throws NullPointerException
     * }</pre>
     *
     * @param value ...

Rules:
  - Exactly one blank Javadoc line before and after the block (blank = prefix + `*`).
  - Inner-class methods keep their existing deeper indentation; every line in the
    block matches the surrounding tag indentation.
  - No double blank lines, no `}</pre>` directly followed by `@param`, no duplicate
    `*` prefixes.
  - `<pre>{@code ... }` is the target form. If converting a plain `<pre>...</pre>`
    block, UNESCAPE HTML entities (&lt; → <, &gt; → >, &amp; → &) since `{@code}`
    is literal. If unsure, leave the existing form.
  - Do NOT introduce raw `\uXXXX` sequences inside `{@code}` — the Java compiler
    decodes them even in comments and will break the build. Write the literal
    character, or split the backslash.

=======================================================================
4. EXAMPLE CONTENT & COMMENT STYLE
=======================================================================
Each line is a real, compilable Java statement or declaration. Declare helper
vars (arrays, lists, maps, predicates, comparators, inputs) inside the block so it
is self-contained — but do not pad; keep it concise. No hidden external state.

Comments: add a trailing comment only when the result/effect/exception is not
obvious. Prefer exact observable results over vague descriptions; use
lowercase/sentence style.
  GOOD:
     * int[] a = {3, 1, 2};
     * N.sort(a);                       // a is [1, 2, 3]
     * N.requireNonNull(null);          // throws NullPointerException
     * List<Boolean> list = flags.boxed(); // converts to List<Boolean>
  AVOID:
     * list.clear();                    // returns void
     * boolean[] a = flags.toArray();   // To primitive array  (title-case / restates code)

Helper declarations need no trailing comment. Do not mechanically add
`// returns ...`. Use section comments inside the block only when they aid
readability of a long, multi-part example; remove them from short, self-evident
blocks.

=======================================================================
5. VALIDATION (per file, before reporting it complete)
=======================================================================
Run scripts with `node scripts/codex/<name>.js`; run the root aligner with python3.
1) Full validation battery (usage/placeholder/example-comment/member-misuse +
   align --check + comment-only diff):
     node scripts/codex/validate_jdoc_usage_slice.js src/main/java Stream.java
   Use the targeted fixers when it flags formatting, e.g.:
     node scripts/codex/move_jdoc_usage_before_tags.js <file>
     node scripts/codex/fix_jdoc_double_blank_lines.js <file>
     node scripts/codex/fix_jdoc_usage_spacing.js <file>
2) Comments-only proof. verify_comment_only_diff.js uses `svn diff` against the
   svn baseline; also sanity-check the git diff shows only comment/`*`/`//` lines:
     node scripts/codex/verify_comment_only_diff.js <file>
3) BUILD MUST STILL COMPILE (catches \uXXXX / `{@code}` breakage):
     mvn -o clean compile
4) Align the examples once green:
     ./scripts/align_jdoc_examples.py --apply <file>
   (or: node scripts/codex/align_jdoc_examples.js --apply <file>)
5) Re-run step 1 after aligning to confirm still green.

Leave all changes UNSTAGED/uncommitted for review. Read each file before editing
so the task is safely re-runnable (skip blocks already correct). New helper scripts,
if genuinely needed, go under ./scripts/codex/ — but check for an existing one first.

=======================================================================
6. REPORT (after Stream.java; then stop for review)
=======================================================================
  - files changed
  - notable correctness fixes (with method names)
  - useful example improvements
  - placeholders / uncertainties left unchanged (and why)
  - validation commands run + their results (incl. `mvn -o clean compile`)
  - confirmation that the diff is comments-only





==============================================================================================================================================

------


TASK: Document Major Classes in a Markdown Table
==================================================

OBJECTIVE
---------
Scan all .java files under ./src/main/java and produce a markdown table that documents the major classes.


SELECTION RULES
---------------
A class qualifies for inclusion only if ALL of the following are true:

  1. It has more than 9 public methods.
  2. It is NOT a non-public inner class (skip these entirely).


OUTPUT FORMAT
-------------
A two-column markdown table with the headers: Classes | Description

Column 1 - "Classes":
  - The parent class name on the first line.
  - Each public inner class name listed below it, one per line.
  - Use <br> for line breaks within the cell.

Column 2 - "Description":
  - A single paragraph describing the combined major functionality
    of the parent class and its inner classes.

Row structure:
  - One row per parent class. All of its public inner classes share
    that same row.


SPECIAL HANDLING
----------------
  1. If a parent class has more than 10 public inner classes, list only
     the top 10 most widely used (ranked by reference count across the
     codebase) and append "..." on a new line to indicate omitted ones.


DELIVERABLES (in order)
-----------------------
Step 1 - Sample for Review:
  Generate a sample table containing ONLY the rows for Numbers and
  Strings. Print it in the chat. Stop and wait for my approval before
  proceeding.

Step 2 - Full Output (after approval):
  a. Generate the full table covering all qualifying classes.
  b. Print the full table in the chat.
  c. Write the same table to ./docs/classes_description.md.


==============================================================================================================================================