docs(javadoc): make document.* public API doclint-clean (#130)

Clear every doclint warning on the public canonical surface
(com.demcha.compose.document.*) so `mvn javadoc:javadoc` (doclint=all)
runs warning-free.

Scope was far larger than first visible: javadoc's default -Xmaxwarns=100
cap surfaced only ~100 warnings, but the true count was 929 across 142
files / 28 packages (raised the cap to enumerate the full set, then
reverted). Mix: 471 no-@param, 191 no-@return, 205 no-comment, 35
no-main-description, 16 use-of-default-constructor, 9 @deprecated-in-
package-info, 2 no-@throws.

Additive Javadoc only, with two sanctioned, behaviour-neutral exceptions:
- 16 explicit no-arg constructors in layout/definitions/* — documents the
  otherwise-synthesised public default constructor (identical behaviour);
  the repo-idiomatic fix for doclint's "use of default constructor".
- removal of the @deprecated block-tags doclint forbids in 9 package-info
  files (the @deprecated annotation + prose body already carry the notice).

No public or runtime behaviour change. Verified: javadoc:javadoc is
warning-clean under doclint=all (real CI config) and the full suite is
green (1060 tests, 0 failures, 0 errors).

Follows cycle 1.6.9 Track N (PR #128 widened javadoc validation to
testing.*); these document.* gaps predate that work.

Author: DemchaAV

CHANGELOG.md

@@ -28,6 +28,17 @@ Housekeeping cycle plus the public pixel-level visual-regression API (Track N).
   pixel-vs-semantic guidance, the `PdfVisualRegression` API, approve mode,
   baseline layout, and cross-platform tolerance calibration.
 - README "Which API should I use?" gains a pixel-level visual-regression row.
+- **Made the entire `com.demcha.compose.document.*` public API Javadoc
+  doclint-clean.** Added the missing `@param` / `@return` / `@throws` tags and
+  element descriptions across 142 files so `mvn javadoc:javadoc`
+  (`doclint=all`) runs warning-free. Java's default `-Xmaxwarns=100` cap had
+  masked ~90% of the gaps (true count: 929 warnings, not the ~100 first
+  visible). Additive Javadoc only — no behaviour change; the only code
+  additions are 16 behaviour-neutral no-arg constructors in
+  `layout/definitions/*` (documenting the otherwise-synthesised public default
+  constructor) and removal of the `@deprecated` block-tags `doclint` forbids in
+  `package-info.java` (the `@Deprecated` annotation + prose body already carry
+  the notice).
 
 ### Build
 

src/main/java/com/demcha/compose/document/api/DocumentSession.java

@@ -405,6 +405,8 @@ public DocumentSession metadata(DocumentMetadata metadata) {
     }
 
     /**
+     * @param options legacy PDF metadata options, or {@code null} to clear
+     * @return this session
      * @deprecated since 1.6.0, removal in v2.0; prefer the canonical
      *             {@link #metadata(DocumentMetadata)}.
      */
@@ -430,6 +432,8 @@ public DocumentSession watermark(DocumentWatermark watermark) {
     }
 
     /**
+     * @param options legacy PDF watermark options, or {@code null} to clear
+     * @return this session
      * @deprecated since 1.6.0, removal in v2.0; prefer the canonical
      *             {@link #watermark(DocumentWatermark)}.
      */
@@ -455,6 +459,8 @@ public DocumentSession protect(DocumentProtection protection) {
     }
 
     /**
+     * @param options legacy PDF protection options, or {@code null} to clear
+     * @return this session
      * @deprecated since 1.6.0, removal in v2.0; prefer the canonical
      *             {@link #protect(DocumentProtection)}.
      */
@@ -479,6 +485,8 @@ public DocumentSession header(DocumentHeaderFooter header) {
     }
 
     /**
+     * @param options legacy PDF header/footer options
+     * @return this session
      * @deprecated since 1.6.0, removal in v2.0; prefer the canonical
      *             {@link #header(DocumentHeaderFooter)}.
      */
@@ -503,6 +511,8 @@ public DocumentSession footer(DocumentHeaderFooter footer) {
     }
 
     /**
+     * @param options legacy PDF header/footer options
+     * @return this session
      * @deprecated since 1.6.0, removal in v2.0; prefer the canonical
      *             {@link #footer(DocumentHeaderFooter)}.
      */

src/main/java/com/demcha/compose/document/api/PageBackgroundFill.java

@@ -52,6 +52,7 @@ public record PageBackgroundFill(double xRatio,
                                  double heightRatio,
                                  DocumentColor color) {
 
+    /** Validates the ratio bounds and that the fill color is non-null. */
     public PageBackgroundFill {
         Objects.requireNonNull(color, "color");
         if (xRatio < 0.0 || xRatio > 1.0) {
@@ -72,60 +73,118 @@ public record PageBackgroundFill(double xRatio,
         }
     }
 
-    /** Full-page fill, equivalent to the legacy single-color page background. */
+    /**
+     * Full-page fill, equivalent to the legacy single-color page background.
+     *
+     * @param color fill color (required)
+     * @return a {@code PageBackgroundFill} that covers the entire page
+     */
     public static PageBackgroundFill fullPage(DocumentColor color) {
         return new PageBackgroundFill(0.0, 0.0, 1.0, 1.0, color);
     }
 
-    /** Full-height column at the left page edge, with width = ratio of page width. */
+    /**
+     * Full-height column at the left page edge, with width = ratio of page width.
+     *
+     * @param widthRatio width as a fraction of the canvas width (0..1]
+     * @param color fill color (required)
+     * @return a {@code PageBackgroundFill} spanning the full page height at the left edge
+     */
     public static PageBackgroundFill leftColumn(double widthRatio,
                                                 DocumentColor color) {
         return new PageBackgroundFill(0.0, 0.0, widthRatio, 1.0, color);
     }
 
-    /** Full-height column at the right page edge, with width = ratio of page width. */
+    /**
+     * Full-height column at the right page edge, with width = ratio of page width.
+     *
+     * @param widthRatio width as a fraction of the canvas width (0..1]
+     * @param color fill color (required)
+     * @return a {@code PageBackgroundFill} spanning the full page height at the right edge
+     */
     public static PageBackgroundFill rightColumn(double widthRatio,
                                                  DocumentColor color) {
         return new PageBackgroundFill(1.0 - widthRatio, 0.0,
                 widthRatio, 1.0, color);
     }
 
-    /** Full-height column at an arbitrary horizontal offset. */
+    /**
+     * Full-height column at an arbitrary horizontal offset.
+     *
+     * @param xRatio left edge of the column: 0.0 = left edge, 1.0 = right edge
+     * @param widthRatio width as a fraction of the canvas width (0..1]
+     * @param color fill color (required)
+     * @return a {@code PageBackgroundFill} spanning the full page height from {@code xRatio}
+     */
     public static PageBackgroundFill column(double xRatio,
                                             double widthRatio,
                                             DocumentColor color) {
         return new PageBackgroundFill(xRatio, 0.0, widthRatio, 1.0, color);
     }
 
-    /** Full-width band flush with the top of the page (height = ratio of page height). */
+    /**
+     * Full-width band flush with the top of the page (height = ratio of page height).
+     *
+     * @param heightRatio height as a fraction of the canvas height (0..1]
+     * @param color fill color (required)
+     * @return a {@code PageBackgroundFill} spanning the full page width at the top edge
+     */
     public static PageBackgroundFill topBand(double heightRatio,
                                              DocumentColor color) {
         return new PageBackgroundFill(0.0, 0.0, 1.0, heightRatio, color);
     }
 
-    /** Full-width band flush with the bottom of the page (height = ratio of page height). */
+    /**
+     * Full-width band flush with the bottom of the page (height = ratio of page height).
+     *
+     * @param heightRatio height as a fraction of the canvas height (0..1]
+     * @param color fill color (required)
+     * @return a {@code PageBackgroundFill} spanning the full page width at the bottom edge
+     */
     public static PageBackgroundFill bottomBand(double heightRatio,
                                                 DocumentColor color) {
         return new PageBackgroundFill(0.0, 1.0 - heightRatio, 1.0,
                 heightRatio, color);
     }
 
-    /** Full-width band whose top edge sits {@code yRatioFromTop} down the page (0.0 = page top). */
+    /**
+     * Full-width band whose top edge sits {@code yRatioFromTop} down the page (0.0 = page top).
+     *
+     * @param yRatioFromTop top edge of the band: 0.0 = page top, 1.0 = page bottom
+     * @param heightRatio height as a fraction of the canvas height (0..1]
+     * @param color fill color (required)
+     * @return a {@code PageBackgroundFill} spanning the full page width from {@code yRatioFromTop}
+     */
     public static PageBackgroundFill band(double yRatioFromTop,
                                           double heightRatio,
                                           DocumentColor color) {
         return new PageBackgroundFill(0.0, yRatioFromTop, 1.0,
                 heightRatio, color);
     }
 
-    /** Top-aligned band sized in absolute points, converted against {@code pageHeight}. */
+    /**
+     * Top-aligned band sized in absolute points, converted against {@code pageHeight}.
+     *
+     * @param heightPoints band height in points
+     * @param pageHeight reference page height in points used to convert points to a ratio
+     * @param color fill color (required)
+     * @return a {@code PageBackgroundFill} spanning the full page width at the top edge
+     */
     public static PageBackgroundFill topBandPoints(double heightPoints,
                                                    double pageHeight,
                                                    DocumentColor color) {
         return topBand(heightPoints / pageHeight, color);
     }
 
-    /** Band positioned and sized in absolute points from the page top, converted against {@code pageHeight}. */
+    /**
+     * Band positioned and sized in absolute points from the page top, converted against {@code pageHeight}.
+     *
+     * @param yFromTopPoints offset of the band top edge from the page top in points
+     * @param heightPoints band height in points
+     * @param pageHeight reference page height in points used to convert points to ratios
+     * @param color fill color (required)
+     * @return a {@code PageBackgroundFill} spanning the full page width from {@code yFromTopPoints}
+     */
     public static PageBackgroundFill bandPoints(double yFromTopPoints,
                                                 double heightPoints,
                                                 double pageHeight,

src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfTableRowFragmentRenderHandler.java

@@ -53,6 +53,11 @@ public void render(PlacedFragment fragment,
      * fragments of a table before rendering borders. Painting fills under the
      * eventual stroke avoids sub-pixel page-background seams around row-span
      * joins.</p>
+     *
+     * @param fragment placed row fragment to render
+     * @param payload table-row payload carrying the resolved cells
+     * @param environment active PDF render environment
+     * @throws java.io.IOException if writing to the PDF content stream fails
      */
     public void renderFills(PlacedFragment fragment,
                             TableRowFragmentPayload payload,
@@ -68,6 +73,11 @@ public void renderFills(PlacedFragment fragment,
 
     /**
      * Paints table cell borders and text for one row fragment.
+     *
+     * @param fragment placed row fragment to render
+     * @param payload table-row payload carrying the resolved cells
+     * @param environment active PDF render environment
+     * @throws java.io.IOException if writing to the PDF content stream fails
      */
     public void renderBordersAndText(PlacedFragment fragment,
                                      TableRowFragmentPayload payload,

src/main/java/com/demcha/compose/document/backend/semantic/SemanticExportContext.java

@@ -36,6 +36,10 @@ public record SemanticExportContext(
 
     /**
      * Backwards-compatible constructor without explicit output options.
+     *
+     * @param canvas physical page canvas for semantic export
+     * @param customFontFamilies document-local font families available to the backend
+     * @param outputFile optional export output file
      */
     public SemanticExportContext(LayoutCanvas canvas,
                                  Collection<FontFamilyDefinition> customFontFamilies,

src/main/java/com/demcha/compose/document/dsl/ShapeContainerBuilder.java

@@ -318,47 +318,92 @@ public ShapeContainerBuilder back(DocumentNode node) {
     // read the same way. Keeping the surface aligned helps autocomplete:
     // "I started with addCircle, the same vocabulary works."
 
-    /** Anchors a layer to the top-left corner. */
+    /**
+     * Anchors a layer to the top-left corner.
+     *
+     * @param node child node
+     * @return this builder
+     */
     public ShapeContainerBuilder topLeft(DocumentNode node) {
         return layer(node, LayerAlign.TOP_LEFT);
     }
 
-    /** Anchors a layer to the top edge, centred horizontally. */
+    /**
+     * Anchors a layer to the top edge, centred horizontally.
+     *
+     * @param node child node
+     * @return this builder
+     */
     public ShapeContainerBuilder topCenter(DocumentNode node) {
         return layer(node, LayerAlign.TOP_CENTER);
     }
 
-    /** Anchors a layer to the top-right corner. */
+    /**
+     * Anchors a layer to the top-right corner.
+     *
+     * @param node child node
+     * @return this builder
+     */
     public ShapeContainerBuilder topRight(DocumentNode node) {
         return layer(node, LayerAlign.TOP_RIGHT);
     }
 
-    /** Anchors a layer to the left edge, centred vertically. */
+    /**
+     * Anchors a layer to the left edge, centred vertically.
+     *
+     * @param node child node
+     * @return this builder
+     */
     public ShapeContainerBuilder centerLeft(DocumentNode node) {
         return layer(node, LayerAlign.CENTER_LEFT);
     }
 
-    /** Centred layer (the typical foreground content above an outline fill). */
+    /**
+     * Centred layer (the typical foreground content above an outline fill).
+     *
+     * @param node child node
+     * @return this builder
+     */
     public ShapeContainerBuilder center(DocumentNode node) {
         return layer(node, LayerAlign.CENTER);
     }
 
-    /** Anchors a layer to the right edge, centred vertically. */
+    /**
+     * Anchors a layer to the right edge, centred vertically.
+     *
+     * @param node child node
+     * @return this builder
+     */
     public ShapeContainerBuilder centerRight(DocumentNode node) {
         return layer(node, LayerAlign.CENTER_RIGHT);
     }
 
-    /** Anchors a layer to the bottom-left corner. */
+    /**
+     * Anchors a layer to the bottom-left corner.
+     *
+     * @param node child node
+     * @return this builder
+     */
     public ShapeContainerBuilder bottomLeft(DocumentNode node) {
         return layer(node, LayerAlign.BOTTOM_LEFT);
     }
 
-    /** Anchors a layer to the bottom edge, centred horizontally. */
+    /**
+     * Anchors a layer to the bottom edge, centred horizontally.
+     *
+     * @param node child node
+     * @return this builder
+     */
     public ShapeContainerBuilder bottomCenter(DocumentNode node) {
         return layer(node, LayerAlign.BOTTOM_CENTER);
     }
 
-    /** Anchors a layer to the bottom-right corner. */
+    /**
+     * Anchors a layer to the bottom-right corner.
+     *
+     * @param node child node
+     * @return this builder
+     */
     public ShapeContainerBuilder bottomRight(DocumentNode node) {
         return layer(node, LayerAlign.BOTTOM_RIGHT);
     }

src/main/java/com/demcha/compose/document/dsl/Transformable.java

@@ -36,6 +36,8 @@ public interface Transformable<T extends Transformable<T>> {
     T transform(DocumentTransform transform);
 
     /**
+     * Returns the transform currently configured on the builder.
+     *
      * @return the transform currently configured on the builder; never
      *         {@code null} (defaults to {@link DocumentTransform#NONE})
      */

src/main/java/com/demcha/compose/document/layout/FixedSlotPlacementContext.java

@@ -8,6 +8,12 @@
  * place into a fixed page band — the parent flow has already decided which
  * page is being filled, so children must not move on by themselves.
  *
+ * @param pageIndex pinned page index that placements land on
+ * @param canvas canvas the placement is happening on
+ * @param prepareContext prepare-phase context used to (re)measure children
+ * @param fragmentContext fragment-emission context forwarded to {@code emitFragments}
+ * @param nodes mutable list of placed semantic nodes; helpers append to this
+ * @param fragments mutable list of placed render fragments; helpers append to this
  * @author Artem Demchyshyn
  */
 public record FixedSlotPlacementContext(

src/main/java/com/demcha/compose/document/layout/NodeDefinitionSupport.java

@@ -459,6 +459,7 @@ public static PreparedSplitResult<TableNode> splitTable(PreparedNode<TableNode>
      * Emits row fragments for a prepared table.
      *
      * @param prepared prepared table node
+     * @param ctx fragment-emission context
      * @param placement resolved fragment placement
      * @return renderer-facing table row fragments
      */