diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a2db633..1cc4fbc9 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/src/main/java/com/demcha/compose/document/api/DocumentSession.java b/src/main/java/com/demcha/compose/document/api/DocumentSession.java index 17f15d58..e9f7cc28 100644 --- a/src/main/java/com/demcha/compose/document/api/DocumentSession.java +++ b/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)}. */ diff --git a/src/main/java/com/demcha/compose/document/api/PageBackgroundFill.java b/src/main/java/com/demcha/compose/document/api/PageBackgroundFill.java index 27abe2ea..f6991ad4 100644 --- a/src/main/java/com/demcha/compose/document/api/PageBackgroundFill.java +++ b/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,45 +73,88 @@ 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) { @@ -118,14 +162,29 @@ public static PageBackgroundFill band(double yRatioFromTop, 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, diff --git a/src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfTableRowFragmentRenderHandler.java b/src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfTableRowFragmentRenderHandler.java index e25fbd8b..2f2a0824 100644 --- a/src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfTableRowFragmentRenderHandler.java +++ b/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.

+ * + * @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, diff --git a/src/main/java/com/demcha/compose/document/backend/semantic/SemanticExportContext.java b/src/main/java/com/demcha/compose/document/backend/semantic/SemanticExportContext.java index 6f73e80a..516b3058 100644 --- a/src/main/java/com/demcha/compose/document/backend/semantic/SemanticExportContext.java +++ b/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 customFontFamilies, diff --git a/src/main/java/com/demcha/compose/document/dsl/ShapeContainerBuilder.java b/src/main/java/com/demcha/compose/document/dsl/ShapeContainerBuilder.java index c63dfc32..471e8bcb 100644 --- a/src/main/java/com/demcha/compose/document/dsl/ShapeContainerBuilder.java +++ b/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); } diff --git a/src/main/java/com/demcha/compose/document/dsl/Transformable.java b/src/main/java/com/demcha/compose/document/dsl/Transformable.java index e5330978..d08c8fca 100644 --- a/src/main/java/com/demcha/compose/document/dsl/Transformable.java +++ b/src/main/java/com/demcha/compose/document/dsl/Transformable.java @@ -36,6 +36,8 @@ public interface Transformable> { 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}) */ diff --git a/src/main/java/com/demcha/compose/document/layout/FixedSlotPlacementContext.java b/src/main/java/com/demcha/compose/document/layout/FixedSlotPlacementContext.java index 737c735f..1305405e 100644 --- a/src/main/java/com/demcha/compose/document/layout/FixedSlotPlacementContext.java +++ b/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( diff --git a/src/main/java/com/demcha/compose/document/layout/NodeDefinitionSupport.java b/src/main/java/com/demcha/compose/document/layout/NodeDefinitionSupport.java index 9ab92dfb..5f8a0424 100644 --- a/src/main/java/com/demcha/compose/document/layout/NodeDefinitionSupport.java +++ b/src/main/java/com/demcha/compose/document/layout/NodeDefinitionSupport.java @@ -459,6 +459,7 @@ public static PreparedSplitResult splitTable(PreparedNode * 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 */ diff --git a/src/main/java/com/demcha/compose/document/layout/PlacementContext.java b/src/main/java/com/demcha/compose/document/layout/PlacementContext.java index 1b1ccdc9..1e3fad91 100644 --- a/src/main/java/com/demcha/compose/document/layout/PlacementContext.java +++ b/src/main/java/com/demcha/compose/document/layout/PlacementContext.java @@ -27,25 +27,53 @@ public sealed interface PlacementContext permits MutatingPlacementContext, FixedSlotPlacementContext { - /** Active page index for placements scheduled through this context. */ + /** + * Active page index for placements scheduled through this context. + * + * @return the active page index + */ int pageIndex(); - /** Canvas the placement is happening on. */ + /** + * Canvas the placement is happening on. + * + * @return the layout canvas + */ LayoutCanvas canvas(); - /** Prepare-phase context used to (re)measure children. */ + /** + * Prepare-phase context used to (re)measure children. + * + * @return the prepare context + */ PrepareContext prepareContext(); - /** Fragment-emission context forwarded to {@code emitFragments}. */ + /** + * Fragment-emission context forwarded to {@code emitFragments}. + * + * @return the fragment context + */ FragmentContext fragmentContext(); - /** Mutable list of placed semantic nodes; helpers append to this. */ + /** + * Mutable list of placed semantic nodes; helpers append to this. + * + * @return the mutable list of placed semantic nodes + */ List nodes(); - /** Mutable list of placed render fragments; helpers append to this. */ + /** + * Mutable list of placed render fragments; helpers append to this. + * + * @return the mutable list of placed render fragments + */ List fragments(); - /** Whether this context can move on to a fresh page. */ + /** + * Whether this context can move on to a fresh page. + * + * @return {@code true} if this context can advance to a fresh page + */ boolean canAdvancePage(); /** diff --git a/src/main/java/com/demcha/compose/document/layout/TextFlowSupport.java b/src/main/java/com/demcha/compose/document/layout/TextFlowSupport.java index 94744552..25bc421e 100644 --- a/src/main/java/com/demcha/compose/document/layout/TextFlowSupport.java +++ b/src/main/java/com/demcha/compose/document/layout/TextFlowSupport.java @@ -59,6 +59,15 @@ private TextFlowSupport() { // Paragraph entry points // ------------------------------------------------------------------ + /** + * Measures a paragraph node and wraps it into a prepared leaf carrying its + * visual line layout. + * + * @param node paragraph node to prepare + * @param ctx prepare-phase context + * @param constraints box constraints for measurement + * @return prepared paragraph node with its line layout + */ public static PreparedNode prepareParagraph(ParagraphNode node, PrepareContext ctx, BoxConstraints constraints) { @@ -74,6 +83,14 @@ public static PreparedNode prepareParagraph(ParagraphNode node, return PreparedNode.leaf(node, measure, layout); } + /** + * Splits a prepared paragraph at the largest line count that fits the + * remaining height. + * + * @param prepared prepared paragraph node + * @param request split request carrying the remaining height + * @return the head/tail split result + */ public static PreparedSplitResult splitParagraph(PreparedNode prepared, SplitRequest request) { ParagraphNode node = prepared.node(); @@ -97,6 +114,13 @@ public static PreparedSplitResult splitParagraph(PreparedNode(head, tail); } + /** + * Emits the render fragment for a prepared paragraph. + * + * @param prepared prepared paragraph node + * @param placement resolved fragment placement + * @return renderer-facing paragraph fragments + */ public static List emitParagraphFragments(PreparedNode prepared, FragmentPlacement placement) { ParagraphNode node = prepared.node(); @@ -126,6 +150,15 @@ public static List emitParagraphFragments(PreparedNode prepareList(ListNode node, PrepareContext ctx, BoxConstraints constraints) { @@ -209,6 +242,14 @@ private static ListMarker defaultMarkerForDepth(int depth) { }; } + /** + * Splits a prepared list at whole-item boundaries, falling back to + * splitting the first item's lines when no whole item fits. + * + * @param prepared prepared list node + * @param request split request carrying the remaining height + * @return the head/tail split result + */ public static PreparedSplitResult splitList(PreparedNode prepared, SplitRequest request) { ListNode node = prepared.node(); @@ -266,6 +307,14 @@ public static PreparedSplitResult splitList(PreparedNode pre return new PreparedSplitResult<>(head, tail); } + /** + * Emits one paragraph fragment per list item so items paginate + * independently. + * + * @param prepared prepared list node + * @param placement resolved fragment placement + * @return renderer-facing per-item fragments + */ public static List emitListFragments(PreparedNode prepared, FragmentPlacement placement) { ListNode node = prepared.node(); diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/BarcodeDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/BarcodeDefinition.java index 7ec90650..7f87e994 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/BarcodeDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/BarcodeDefinition.java @@ -25,6 +25,13 @@ * @author Artem Demchyshyn */ public final class BarcodeDefinition implements NodeDefinition { + + /** + * Creates the barcode layout definition. + */ + public BarcodeDefinition() { + } + @Override public Class nodeType() { return BarcodeNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/CanvasLayerDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/CanvasLayerDefinition.java index da164ab6..697a451f 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/CanvasLayerDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/CanvasLayerDefinition.java @@ -42,6 +42,12 @@ */ public final class CanvasLayerDefinition implements NodeDefinition { + /** + * Creates the canvas-layer layout definition. + */ + public CanvasLayerDefinition() { + } + @Override public Class nodeType() { return CanvasLayerNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/ContainerDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/ContainerDefinition.java index b00f9cc6..b77ea5c7 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/ContainerDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/ContainerDefinition.java @@ -27,6 +27,13 @@ * @author Artem Demchyshyn */ public final class ContainerDefinition implements NodeDefinition { + + /** + * Creates the container layout definition. + */ + public ContainerDefinition() { + } + @Override public Class nodeType() { return ContainerNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/EllipseDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/EllipseDefinition.java index 9bf739fa..568335c4 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/EllipseDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/EllipseDefinition.java @@ -25,6 +25,13 @@ * @author Artem Demchyshyn */ public final class EllipseDefinition implements NodeDefinition { + + /** + * Creates the ellipse layout definition. + */ + public EllipseDefinition() { + } + @Override public Class nodeType() { return EllipseNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/ImageDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/ImageDefinition.java index c71a0710..07097565 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/ImageDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/ImageDefinition.java @@ -28,6 +28,13 @@ * @author Artem Demchyshyn */ public final class ImageDefinition implements NodeDefinition { + + /** + * Creates the image layout definition. + */ + public ImageDefinition() { + } + @Override public Class nodeType() { return ImageNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/LayerStackDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/LayerStackDefinition.java index e85c10c0..072c9917 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/LayerStackDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/LayerStackDefinition.java @@ -26,6 +26,13 @@ * @author Artem Demchyshyn */ public final class LayerStackDefinition implements NodeDefinition { + + /** + * Creates the layer-stack layout definition. + */ + public LayerStackDefinition() { + } + @Override public Class nodeType() { return LayerStackNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/LineDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/LineDefinition.java index 9dc1f176..94f51fa6 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/LineDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/LineDefinition.java @@ -25,6 +25,13 @@ * @author Artem Demchyshyn */ public final class LineDefinition implements NodeDefinition { + + /** + * Creates the line layout definition. + */ + public LineDefinition() { + } + @Override public Class nodeType() { return LineNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/ListDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/ListDefinition.java index 13237a8c..68b4bbea 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/ListDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/ListDefinition.java @@ -27,6 +27,13 @@ * @author Artem Demchyshyn */ public final class ListDefinition implements NodeDefinition { + + /** + * Creates the list layout definition. + */ + public ListDefinition() { + } + @Override public Class nodeType() { return ListNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/PageBreakDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/PageBreakDefinition.java index 2dad7ba7..683205a1 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/PageBreakDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/PageBreakDefinition.java @@ -24,6 +24,12 @@ */ public final class PageBreakDefinition implements NodeDefinition { + /** + * Creates the page-break layout definition. + */ + public PageBreakDefinition() { + } + @Override public Class nodeType() { return PageBreakNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/ParagraphDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/ParagraphDefinition.java index f2a047b7..eb60a845 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/ParagraphDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/ParagraphDefinition.java @@ -26,6 +26,13 @@ * @author Artem Demchyshyn */ public final class ParagraphDefinition implements NodeDefinition { + + /** + * Creates the paragraph layout definition. + */ + public ParagraphDefinition() { + } + @Override public Class nodeType() { return ParagraphNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/RowDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/RowDefinition.java index 1023af4f..f938aed0 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/RowDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/RowDefinition.java @@ -27,6 +27,13 @@ * @author Artem Demchyshyn */ public final class RowDefinition implements NodeDefinition { + + /** + * Creates the row layout definition. + */ + public RowDefinition() { + } + @Override public Class nodeType() { return RowNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/SectionDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/SectionDefinition.java index 35b32d39..9180ae8f 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/SectionDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/SectionDefinition.java @@ -27,6 +27,13 @@ * @author Artem Demchyshyn */ public final class SectionDefinition implements NodeDefinition { + + /** + * Creates the section layout definition. + */ + public SectionDefinition() { + } + @Override public Class nodeType() { return SectionNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/ShapeContainerDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/ShapeContainerDefinition.java index c6c45441..fd27f4a7 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/ShapeContainerDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/ShapeContainerDefinition.java @@ -41,6 +41,13 @@ * @author Artem Demchyshyn */ public final class ShapeContainerDefinition implements NodeDefinition { + + /** + * Creates the shape-container layout definition. + */ + public ShapeContainerDefinition() { + } + @Override public Class nodeType() { return ShapeContainerNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/ShapeDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/ShapeDefinition.java index b743a6a4..e0871bb1 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/ShapeDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/ShapeDefinition.java @@ -26,6 +26,13 @@ * @author Artem Demchyshyn */ public final class ShapeDefinition implements NodeDefinition { + + /** + * Creates the shape layout definition. + */ + public ShapeDefinition() { + } + @Override public Class nodeType() { return ShapeNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/SpacerDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/SpacerDefinition.java index c627a6c8..2e7096d7 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/SpacerDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/SpacerDefinition.java @@ -23,6 +23,12 @@ */ public final class SpacerDefinition implements NodeDefinition { + /** + * Creates the spacer layout definition. + */ + public SpacerDefinition() { + } + @Override public Class nodeType() { return SpacerNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/TableDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/TableDefinition.java index f6606712..5b02d2d6 100644 --- a/src/main/java/com/demcha/compose/document/layout/definitions/TableDefinition.java +++ b/src/main/java/com/demcha/compose/document/layout/definitions/TableDefinition.java @@ -26,6 +26,13 @@ * @author Artem Demchyshyn */ public final class TableDefinition implements NodeDefinition { + + /** + * Creates the table layout definition. + */ + public TableDefinition() { + } + @Override public Class nodeType() { return TableNode.class; diff --git a/src/main/java/com/demcha/compose/document/layout/payloads/ParagraphSpan.java b/src/main/java/com/demcha/compose/document/layout/payloads/ParagraphSpan.java index 73bf30d2..e5a165db 100644 --- a/src/main/java/com/demcha/compose/document/layout/payloads/ParagraphSpan.java +++ b/src/main/java/com/demcha/compose/document/layout/payloads/ParagraphSpan.java @@ -9,16 +9,22 @@ */ public sealed interface ParagraphSpan permits ParagraphTextSpan, ParagraphImageSpan { /** + * Measured width of this span. + * * @return measured span width in points */ double width(); /** + * Link metadata anchored to this span, if any. + * * @return optional link metadata anchored to this span */ DocumentLinkOptions linkOptions(); /** + * Height this span contributes to its line. + * * @return effective height contribution for line metrics (font line * height for text spans, image height for image spans) */ diff --git a/src/main/java/com/demcha/compose/document/node/BarcodeNode.java b/src/main/java/com/demcha/compose/document/node/BarcodeNode.java index 326688b7..0d0ddd12 100644 --- a/src/main/java/com/demcha/compose/document/node/BarcodeNode.java +++ b/src/main/java/com/demcha/compose/document/node/BarcodeNode.java @@ -55,6 +55,13 @@ public record BarcodeNode( /** * Backward-compatible convenience constructor without link/bookmark metadata. + * + * @param name node name used in snapshots and layout graph paths + * @param barcodeOptions canonical barcode payload + * @param width target rendered width + * @param height target rendered height + * @param padding inner padding + * @param margin outer margin */ public BarcodeNode(String name, DocumentBarcodeOptions barcodeOptions, @@ -68,6 +75,15 @@ public BarcodeNode(String name, /** * Backward-compatible convenience constructor without transform — defaults * to {@link DocumentTransform#NONE}. + * + * @param name node name used in snapshots and layout graph paths + * @param barcodeOptions canonical barcode payload + * @param width target rendered width + * @param height target rendered height + * @param linkOptions optional node-level link metadata + * @param bookmarkOptions optional node-level bookmark metadata + * @param padding inner padding + * @param margin outer margin */ public BarcodeNode(String name, DocumentBarcodeOptions barcodeOptions, diff --git a/src/main/java/com/demcha/compose/document/node/ContainerNode.java b/src/main/java/com/demcha/compose/document/node/ContainerNode.java index 498167b4..96115964 100644 --- a/src/main/java/com/demcha/compose/document/node/ContainerNode.java +++ b/src/main/java/com/demcha/compose/document/node/ContainerNode.java @@ -53,6 +53,15 @@ public record ContainerNode( /** * Creates a vertical flow container without per-side borders. + * + * @param name node name used in snapshots and layout graph paths + * @param children child semantic nodes in source order + * @param spacing vertical spacing between children + * @param padding inner padding + * @param margin outer margin + * @param fillColor optional background fill + * @param stroke optional uniform border stroke + * @param cornerRadius optional render-only corner radius */ public ContainerNode(String name, List children, @@ -67,6 +76,14 @@ public ContainerNode(String name, /** * Creates a vertical flow container with square corners and no per-side borders. + * + * @param name node name used in snapshots and layout graph paths + * @param children child semantic nodes in source order + * @param spacing vertical spacing between children + * @param padding inner padding + * @param margin outer margin + * @param fillColor optional background fill + * @param stroke optional uniform border stroke */ public ContainerNode(String name, List children, diff --git a/src/main/java/com/demcha/compose/document/node/EllipseNode.java b/src/main/java/com/demcha/compose/document/node/EllipseNode.java index e1ad3b32..a7e469aa 100644 --- a/src/main/java/com/demcha/compose/document/node/EllipseNode.java +++ b/src/main/java/com/demcha/compose/document/node/EllipseNode.java @@ -52,6 +52,16 @@ public record EllipseNode( /** * Backward-compatible convenience constructor without transform — defaults * to {@link DocumentTransform#NONE}. + * + * @param name node name used in snapshots and layout graph paths + * @param width resolved ellipse width + * @param height resolved ellipse height + * @param fillColor optional fill color + * @param stroke optional stroke descriptor + * @param linkOptions optional node-level link metadata + * @param bookmarkOptions optional node-level bookmark metadata + * @param padding inner padding + * @param margin outer margin */ public EllipseNode(String name, double width, diff --git a/src/main/java/com/demcha/compose/document/node/ImageNode.java b/src/main/java/com/demcha/compose/document/node/ImageNode.java index b4e9d180..b5c05507 100644 --- a/src/main/java/com/demcha/compose/document/node/ImageNode.java +++ b/src/main/java/com/demcha/compose/document/node/ImageNode.java @@ -61,6 +61,13 @@ public record ImageNode( /** * Backward-compatible convenience constructor without link/bookmark metadata. + * + * @param name node name used in snapshots and layout graph paths + * @param imageData semantic image payload + * @param width optional target width + * @param height optional target height + * @param padding inner padding + * @param margin outer margin */ public ImageNode(String name, DocumentImageData imageData, @@ -73,6 +80,15 @@ public ImageNode(String name, /** * Backward-compatible convenience constructor without image fit options. + * + * @param name node name used in snapshots and layout graph paths + * @param imageData semantic image payload + * @param width optional target width + * @param height optional target height + * @param linkOptions optional node-level link metadata + * @param bookmarkOptions optional node-level bookmark metadata + * @param padding inner padding + * @param margin outer margin */ public ImageNode(String name, DocumentImageData imageData, @@ -88,6 +104,17 @@ public ImageNode(String name, /** * Backward-compatible convenience constructor without transform — defaults * to {@link DocumentTransform#NONE}. + * + * @param name node name used in snapshots and layout graph paths + * @param imageData semantic image payload + * @param width optional target width + * @param height optional target height + * @param scale optional uniform scale applied when width and height are omitted + * @param fitMode image fit policy used when drawing inside explicit bounds + * @param linkOptions optional node-level link metadata + * @param bookmarkOptions optional node-level bookmark metadata + * @param padding inner padding + * @param margin outer margin */ public ImageNode(String name, DocumentImageData imageData, diff --git a/src/main/java/com/demcha/compose/document/node/LineNode.java b/src/main/java/com/demcha/compose/document/node/LineNode.java index 0c4ad075..9695cd85 100644 --- a/src/main/java/com/demcha/compose/document/node/LineNode.java +++ b/src/main/java/com/demcha/compose/document/node/LineNode.java @@ -57,6 +57,19 @@ public record LineNode( /** * Backward-compatible convenience constructor without transform — defaults * to {@link DocumentTransform#NONE}. + * + * @param name node name used in snapshots and layout graph paths + * @param width resolved line box width + * @param height resolved line box height + * @param startX line start x offset inside the box + * @param startY line start y offset inside the box + * @param endX line end x offset inside the box + * @param endY line end y offset inside the box + * @param stroke line stroke descriptor + * @param linkOptions optional node-level link metadata + * @param bookmarkOptions optional node-level bookmark metadata + * @param padding inner padding + * @param margin outer margin */ public LineNode(String name, double width, diff --git a/src/main/java/com/demcha/compose/document/node/ListNode.java b/src/main/java/com/demcha/compose/document/node/ListNode.java index 729f4596..a6242a26 100644 --- a/src/main/java/com/demcha/compose/document/node/ListNode.java +++ b/src/main/java/com/demcha/compose/document/node/ListNode.java @@ -82,6 +82,18 @@ public record ListNode( /** * Back-compat constructor matching the v1.4 / v1.5 11-component * signature. Treats the list as flat (no nested items). + * + * @param name optional semantic name used in snapshots and diagnostics + * @param items item texts in source order — used when {@code nestedItems} is empty + * @param marker top-level marker rendered before each flat item + * @param textStyle shared item text style + * @param align horizontal alignment for item text + * @param lineSpacing extra space between wrapped lines within one item + * @param itemSpacing extra space between list items + * @param continuationIndent prefix used only for wrapped continuation lines when the marker is hidden + * @param normalizeMarkers whether leading user-supplied bullets or dashes are stripped + * @param padding inner list padding + * @param margin outer list margin */ public ListNode(String name, List items, diff --git a/src/main/java/com/demcha/compose/document/node/ParagraphNode.java b/src/main/java/com/demcha/compose/document/node/ParagraphNode.java index f6a6dec1..33725358 100644 --- a/src/main/java/com/demcha/compose/document/node/ParagraphNode.java +++ b/src/main/java/com/demcha/compose/document/node/ParagraphNode.java @@ -26,6 +26,7 @@ * @param bookmarkOptions optional node-level bookmark metadata * @param padding inner padding * @param margin outer margin + * @param autoSize optional automatic font down-scaling policy * @author Artem Demchyshyn */ public record ParagraphNode( @@ -73,6 +74,20 @@ public record ParagraphNode( /** * Backwards-compatible 12-arg canonical constructor without auto-size. + * + * @param name node name used in snapshots and layout graph paths + * @param text paragraph text when inline runs are not supplied + * @param inlineRuns optional inline runs in source order; may mix text and + * image runs and is wrapped on a single baseline + * @param textStyle base paragraph text style + * @param align horizontal text alignment + * @param lineSpacing extra space between wrapped lines + * @param bulletOffset first-line prefix used by list-style paragraph paths + * @param indentStrategy hanging/first-line indent strategy + * @param linkOptions optional node-level link metadata + * @param bookmarkOptions optional node-level bookmark metadata + * @param padding inner padding + * @param margin outer margin */ public ParagraphNode(String name, String text, diff --git a/src/main/java/com/demcha/compose/document/node/RowNode.java b/src/main/java/com/demcha/compose/document/node/RowNode.java index 60cc94ec..70309cff 100644 --- a/src/main/java/com/demcha/compose/document/node/RowNode.java +++ b/src/main/java/com/demcha/compose/document/node/RowNode.java @@ -32,6 +32,7 @@ * @param fillColor optional background fill * @param stroke optional border stroke * @param cornerRadius optional render-only corner radius + * @param borders optional per-side border strokes overriding the uniform stroke * * @author Artem Demchyshyn */ @@ -75,6 +76,16 @@ public record RowNode( /** * Backwards-compatible constructor without per-side borders. + * + * @param name node name used in snapshots and layout graph paths + * @param children child semantic nodes in source order + * @param weights optional per-child weights (length must match children, or be empty) + * @param gap horizontal gap between children + * @param padding inner padding + * @param margin outer margin + * @param fillColor optional background fill + * @param stroke optional border stroke + * @param cornerRadius optional render-only corner radius */ public RowNode(String name, List children, diff --git a/src/main/java/com/demcha/compose/document/node/SectionNode.java b/src/main/java/com/demcha/compose/document/node/SectionNode.java index 260af518..0a17ed1c 100644 --- a/src/main/java/com/demcha/compose/document/node/SectionNode.java +++ b/src/main/java/com/demcha/compose/document/node/SectionNode.java @@ -53,6 +53,15 @@ public record SectionNode( /** * Creates a vertical semantic section without per-side borders. + * + * @param name node name used in snapshots and layout graph paths + * @param children child semantic nodes in source order + * @param spacing vertical spacing between children + * @param padding inner padding + * @param margin outer margin + * @param fillColor optional background fill + * @param stroke optional uniform border stroke + * @param cornerRadius optional render-only corner radius */ public SectionNode(String name, List children, @@ -67,6 +76,14 @@ public SectionNode(String name, /** * Creates a vertical semantic section with square corners and no per-side borders. + * + * @param name node name used in snapshots and layout graph paths + * @param children child semantic nodes in source order + * @param spacing vertical spacing between children + * @param padding inner padding + * @param margin outer margin + * @param fillColor optional background fill + * @param stroke optional uniform border stroke */ public SectionNode(String name, List children, diff --git a/src/main/java/com/demcha/compose/document/node/ShapeNode.java b/src/main/java/com/demcha/compose/document/node/ShapeNode.java index ff0d23db..eb9fbe2f 100644 --- a/src/main/java/com/demcha/compose/document/node/ShapeNode.java +++ b/src/main/java/com/demcha/compose/document/node/ShapeNode.java @@ -61,6 +61,14 @@ public record ShapeNode( /** * Backward-compatible convenience constructor without link/bookmark metadata. + * + * @param name node name used in snapshots and layout graph paths + * @param width resolved shape width + * @param height resolved shape height + * @param fillColor optional fill color + * @param stroke optional stroke descriptor + * @param padding inner padding + * @param margin outer margin */ public ShapeNode(String name, double width, @@ -75,6 +83,16 @@ public ShapeNode(String name, /** * Backward-compatible convenience constructor without corner radius. + * + * @param name node name used in snapshots and layout graph paths + * @param width resolved shape width + * @param height resolved shape height + * @param fillColor optional fill color + * @param stroke optional stroke descriptor + * @param linkOptions optional node-level link metadata + * @param bookmarkOptions optional node-level bookmark metadata + * @param padding inner padding + * @param margin outer margin */ public ShapeNode(String name, double width, @@ -91,6 +109,17 @@ public ShapeNode(String name, /** * Backward-compatible convenience constructor without transform — defaults * to {@link DocumentTransform#NONE}. + * + * @param name node name used in snapshots and layout graph paths + * @param width resolved shape width + * @param height resolved shape height + * @param fillColor optional fill color + * @param stroke optional stroke descriptor + * @param cornerRadius optional render-only corner radius + * @param linkOptions optional node-level link metadata + * @param bookmarkOptions optional node-level bookmark metadata + * @param padding inner padding + * @param margin outer margin */ public ShapeNode(String name, double width, diff --git a/src/main/java/com/demcha/compose/document/node/TableNode.java b/src/main/java/com/demcha/compose/document/node/TableNode.java index 067e7b38..671078c3 100644 --- a/src/main/java/com/demcha/compose/document/node/TableNode.java +++ b/src/main/java/com/demcha/compose/document/node/TableNode.java @@ -97,6 +97,18 @@ public TableNode(String name, /** * Backward-compatible 11-arg constructor (pre-Phase D.3) that defaults * {@code repeatedHeaderRowCount} to {@code 0}. + * + * @param name table node name used in snapshots and layout graph paths + * @param columns negotiated table columns + * @param rows table rows in source order + * @param defaultCellStyle default cell style applied to every cell + * @param rowStyles row-specific style overrides + * @param columnStyles column-specific style overrides + * @param width optional explicit table width + * @param linkOptions optional node-level link metadata + * @param bookmarkOptions optional node-level bookmark metadata + * @param padding outer table padding + * @param margin outer table margin */ public TableNode(String name, List columns, diff --git a/src/main/java/com/demcha/compose/document/output/DocumentHeaderFooterZone.java b/src/main/java/com/demcha/compose/document/output/DocumentHeaderFooterZone.java index af3c9d06..b8b3b983 100644 --- a/src/main/java/com/demcha/compose/document/output/DocumentHeaderFooterZone.java +++ b/src/main/java/com/demcha/compose/document/output/DocumentHeaderFooterZone.java @@ -6,6 +6,8 @@ * @author Artem Demchyshyn */ public enum DocumentHeaderFooterZone { + /** Top-of-page header zone. */ HEADER, + /** Bottom-of-page footer zone. */ FOOTER } diff --git a/src/main/java/com/demcha/compose/document/output/DocumentWatermarkPosition.java b/src/main/java/com/demcha/compose/document/output/DocumentWatermarkPosition.java index 4c0fc629..02189f79 100644 --- a/src/main/java/com/demcha/compose/document/output/DocumentWatermarkPosition.java +++ b/src/main/java/com/demcha/compose/document/output/DocumentWatermarkPosition.java @@ -8,10 +8,15 @@ * @author Artem Demchyshyn */ public enum DocumentWatermarkPosition { + /** Single watermark centred on the page. */ CENTER, + /** Single watermark anchored to the top-left corner. */ TOP_LEFT, + /** Single watermark anchored to the top-right corner. */ TOP_RIGHT, + /** Single watermark anchored to the bottom-left corner. */ BOTTOM_LEFT, + /** Single watermark anchored to the bottom-right corner. */ BOTTOM_RIGHT, /** Repeated tiled watermark pattern across the page. */ TILE diff --git a/src/main/java/com/demcha/compose/document/style/DocumentCornerRadius.java b/src/main/java/com/demcha/compose/document/style/DocumentCornerRadius.java index 0b2fdb9f..5d68b6e5 100644 --- a/src/main/java/com/demcha/compose/document/style/DocumentCornerRadius.java +++ b/src/main/java/com/demcha/compose/document/style/DocumentCornerRadius.java @@ -137,6 +137,8 @@ public double radius() { } /** + * Reports whether every corner radius equals zero. + * * @return whether every corner radius equals zero */ public boolean isZero() { @@ -144,6 +146,8 @@ public boolean isZero() { } /** + * Reports whether every corner has the same radius value. + * * @return whether every corner has the same radius value */ public boolean isUniform() { diff --git a/src/main/java/com/demcha/compose/document/style/DocumentTransform.java b/src/main/java/com/demcha/compose/document/style/DocumentTransform.java index 430a9780..a537c5d5 100644 --- a/src/main/java/com/demcha/compose/document/style/DocumentTransform.java +++ b/src/main/java/com/demcha/compose/document/style/DocumentTransform.java @@ -44,6 +44,8 @@ public record DocumentTransform(double rotationDegrees, double scaleX, double sc } /** + * Returns the identity transform. + * * @return the identity transform (alias for {@link #NONE}) */ public static DocumentTransform none() { @@ -51,6 +53,8 @@ public static DocumentTransform none() { } /** + * Creates a rotation-only transform with identity scaling. + * * @param degrees clockwise rotation in degrees * @return a transform that only rotates, with identity scaling */ @@ -80,6 +84,8 @@ public static DocumentTransform scale(double scaleX, double scaleY) { } /** + * Returns a copy of this transform with the rotation replaced. + * * @param degrees clockwise rotation in degrees * @return a copy of this transform with the rotation replaced */ @@ -88,6 +94,8 @@ public DocumentTransform withRotation(double degrees) { } /** + * Returns a copy of this transform with the scale factors replaced. + * * @param scaleX horizontal scale factor * @param scaleY vertical scale factor * @return a copy of this transform with the scale factors replaced @@ -97,6 +105,8 @@ public DocumentTransform withScale(double scaleX, double scaleY) { } /** + * Reports whether this transform is the identity. + * * @return {@code true} when the transform is the identity (no * rotation, no scaling); backends may skip CTM push/pop * when this is the case diff --git a/src/main/java/com/demcha/compose/document/style/ShapeOutline.java b/src/main/java/com/demcha/compose/document/style/ShapeOutline.java index 707df568..29d89507 100644 --- a/src/main/java/com/demcha/compose/document/style/ShapeOutline.java +++ b/src/main/java/com/demcha/compose/document/style/ShapeOutline.java @@ -17,11 +17,15 @@ public sealed interface ShapeOutline permits ShapeOutline.Ellipse { /** + * Returns the outline outer width. + * * @return outline outer width in points */ double width(); /** + * Returns the outline outer height. + * * @return outline outer height in points */ double height(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/layouts/package-info.java b/src/main/java/com/demcha/compose/document/templates/coverletter/layouts/package-info.java index 106290a3..085dabf0 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/layouts/package-info.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/layouts/package-info.java @@ -18,11 +18,6 @@ * instead. See {@code docs/templates/v2-layered/}.

* * @since 1.6.0 - * @deprecated Superseded by the layered - * {@code com.demcha.compose.document.templates.coverletter.v2} - * surface (the current standard). This Gen-2 package is kept for - * backward compatibility and will be removed in a future major. - * See {@code docs/templates/v2-layered/}. */ @Deprecated(since = "1.7.0", forRemoval = true) package com.demcha.compose.document.templates.coverletter.layouts; diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/package-info.java b/src/main/java/com/demcha/compose/document/templates/coverletter/package-info.java index 5e191747..818e6a9b 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/package-info.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/package-info.java @@ -37,11 +37,6 @@ * (e.g. {@code cover-letter-modern-professional.pdf}).

* * @since 1.6.0 - * @deprecated Superseded by the layered - * {@code com.demcha.compose.document.templates.coverletter.v2} - * surface (the current standard). This Gen-2 package is kept for - * backward compatibility and will be removed in a future major. - * See {@code docs/templates/v2-layered/}. */ @Deprecated(since = "1.7.0", forRemoval = true) package com.demcha.compose.document.templates.coverletter; diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/BlueBannerLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/BlueBannerLetter.java index cf0f4b55..d733e065 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/BlueBannerLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/BlueBannerLetter.java @@ -41,6 +41,12 @@ public final class BlueBannerLetter { private BlueBannerLetter() { } + /** + * Builds the cover-letter template paired with the {@code BlueBanner} CV preset. + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Blue Banner Letter" + */ public static DocumentTemplate create(BusinessTheme theme) { Spacing spacing = Spacing.comfortable(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/BoxedSectionsLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/BoxedSectionsLetter.java index 4d37092e..0c78c124 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/BoxedSectionsLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/BoxedSectionsLetter.java @@ -39,6 +39,12 @@ public final class BoxedSectionsLetter { private BoxedSectionsLetter() { } + /** + * Builds the cover-letter template paired with the {@code BoxedSections} CV preset. + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Boxed Sections Letter" + */ public static DocumentTemplate create(BusinessTheme theme) { Spacing spacing = Spacing.comfortable(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/CenteredHeadlineLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/CenteredHeadlineLetter.java index 1afe6de7..938f5d65 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/CenteredHeadlineLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/CenteredHeadlineLetter.java @@ -40,6 +40,12 @@ public final class CenteredHeadlineLetter { private CenteredHeadlineLetter() { } + /** + * Builds the cover-letter template paired with the {@code CenteredHeadline} CV preset. + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Centered Headline Letter" + */ public static DocumentTemplate create(BusinessTheme theme) { Spacing spacing = Spacing.comfortable(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/ClassicSerifLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/ClassicSerifLetter.java index 69007a25..452f89e8 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/ClassicSerifLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/ClassicSerifLetter.java @@ -39,6 +39,12 @@ public final class ClassicSerifLetter { private ClassicSerifLetter() { } + /** + * Builds the cover-letter template paired with the {@code ClassicSerif} CV preset. + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Classic Serif Letter" + */ public static DocumentTemplate create(BusinessTheme theme) { Spacing spacing = Spacing.comfortable(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/CompactMonoLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/CompactMonoLetter.java index 50412499..1e3224ea 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/CompactMonoLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/CompactMonoLetter.java @@ -40,6 +40,12 @@ public final class CompactMonoLetter { private CompactMonoLetter() { } + /** + * Builds the cover-letter template paired with the {@code CompactMono} CV preset. + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Compact Mono Letter" + */ public static DocumentTemplate create(BusinessTheme theme) { Spacing spacing = Spacing.compact(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/EditorialBlueLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/EditorialBlueLetter.java index 513f885c..72898fea 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/EditorialBlueLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/EditorialBlueLetter.java @@ -40,6 +40,12 @@ public final class EditorialBlueLetter { private EditorialBlueLetter() { } + /** + * Builds the cover-letter template paired with the {@code EditorialBlue} CV preset. + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Editorial Blue Letter" + */ public static DocumentTemplate create(BusinessTheme theme) { Spacing spacing = Spacing.comfortable(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/EngineeringResumeLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/EngineeringResumeLetter.java index 70eeeecd..105985f8 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/EngineeringResumeLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/EngineeringResumeLetter.java @@ -40,6 +40,12 @@ public final class EngineeringResumeLetter { private EngineeringResumeLetter() { } + /** + * Builds the cover-letter template paired with the {@code EngineeringResume} CV preset. + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Engineering Resume Letter" + */ public static DocumentTemplate create(BusinessTheme theme) { Spacing spacing = Spacing.compact(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/ExecutiveLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/ExecutiveLetter.java index 12101ddd..76a1ba80 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/ExecutiveLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/ExecutiveLetter.java @@ -39,6 +39,12 @@ public final class ExecutiveLetter { private ExecutiveLetter() { } + /** + * Builds the cover-letter template paired with the {@code Executive} CV preset. + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Executive Letter" + */ public static DocumentTemplate create(BusinessTheme theme) { Spacing spacing = Spacing.comfortable(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/MonogramSidebarLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/MonogramSidebarLetter.java index 85ec4bb0..b37b3d18 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/MonogramSidebarLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/MonogramSidebarLetter.java @@ -42,6 +42,12 @@ public final class MonogramSidebarLetter { private MonogramSidebarLetter() { } + /** + * Builds the cover-letter template paired with the {@code MonogramSidebar} CV preset. + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Monogram Sidebar Letter" + */ public static DocumentTemplate create(BusinessTheme theme) { Spacing spacing = Spacing.comfortable(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/PanelLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/PanelLetter.java index c41726d3..c466cdb6 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/PanelLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/PanelLetter.java @@ -39,6 +39,12 @@ public final class PanelLetter { private PanelLetter() { } + /** + * Builds the cover-letter template paired with the {@code Panel} CV preset. + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Panel Letter" + */ public static DocumentTemplate create(BusinessTheme theme) { Spacing spacing = Spacing.comfortable(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/SidebarPortraitLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/SidebarPortraitLetter.java index 8a7ce9c2..5da97e3a 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/SidebarPortraitLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/SidebarPortraitLetter.java @@ -42,6 +42,12 @@ public final class SidebarPortraitLetter { private SidebarPortraitLetter() { } + /** + * Builds the cover-letter template paired with the {@code SidebarPortrait} CV preset. + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Sidebar Portrait Letter" + */ public static DocumentTemplate create(BusinessTheme theme) { Spacing spacing = Spacing.comfortable(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/TimelineMinimalLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/TimelineMinimalLetter.java index 20473f35..fbf27f9f 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/TimelineMinimalLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/TimelineMinimalLetter.java @@ -39,6 +39,12 @@ public final class TimelineMinimalLetter { private TimelineMinimalLetter() { } + /** + * Builds the cover-letter template paired with the {@code TimelineMinimal} CV preset. + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Timeline Minimal Letter" + */ public static DocumentTemplate create(BusinessTheme theme) { Spacing spacing = Spacing.comfortable(); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/package-info.java b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/package-info.java index 76661b47..0bea3e7c 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/presets/package-info.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/presets/package-info.java @@ -19,11 +19,6 @@ * instead. See {@code docs/templates/v2-layered/}.

* * @since 1.6.0 - * @deprecated Superseded by the layered - * {@code com.demcha.compose.document.templates.coverletter.v2} - * surface (the current standard). This Gen-2 package is kept for - * backward compatibility and will be removed in a future major. - * See {@code docs/templates/v2-layered/}. */ @Deprecated(since = "1.7.0", forRemoval = true) package com.demcha.compose.document.templates.coverletter.presets; diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/spec/package-info.java b/src/main/java/com/demcha/compose/document/templates/coverletter/spec/package-info.java index 3f591eb8..ea846a96 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/spec/package-info.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/spec/package-info.java @@ -27,11 +27,6 @@ * instead. See {@code docs/templates/v2-layered/}.

* * @since 1.6.0 - * @deprecated Superseded by the layered - * {@code com.demcha.compose.document.templates.coverletter.v2} - * surface (the current standard). This Gen-2 package is kept for - * backward compatibility and will be removed in a future major. - * See {@code docs/templates/v2-layered/}. */ @Deprecated(since = "1.7.0", forRemoval = true) package com.demcha.compose.document.templates.coverletter.spec; diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/data/CoverLetterDocument.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/data/CoverLetterDocument.java index 58090336..6b5b5a1a 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/data/CoverLetterDocument.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/data/CoverLetterDocument.java @@ -51,6 +51,8 @@ public record CoverLetterDocument(CvIdentity identity, } /** + * Creates a new fluent builder. + * * @return new fluent builder */ public static Builder builder() { diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/BlueBannerLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/BlueBannerLetter.java index 7d4653c0..125fa917 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/BlueBannerLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/BlueBannerLetter.java @@ -43,6 +43,8 @@ private BlueBannerLetter() { /** * Builds the letter with its Blue Banner theme. + * + * @return a {@code DocumentTemplate} for the "Blue Banner Letter" */ public static DocumentTemplate create() { return create(CvTheme.blueBanner()); @@ -51,6 +53,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Blue Banner Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/BoxedSectionsLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/BoxedSectionsLetter.java index 0e3b213e..6abca94f 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/BoxedSectionsLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/BoxedSectionsLetter.java @@ -42,6 +42,8 @@ private BoxedSectionsLetter() { /** * Builds the letter with its Boxed Sections theme. + * + * @return a {@code DocumentTemplate} for the "Boxed Sections Letter" */ public static DocumentTemplate create() { return create(CvTheme.boxedClassic()); @@ -50,6 +52,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Boxed Sections Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/CenteredHeadlineLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/CenteredHeadlineLetter.java index 39e10488..dc26f02c 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/CenteredHeadlineLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/CenteredHeadlineLetter.java @@ -52,6 +52,8 @@ private CenteredHeadlineLetter() { /** * Builds the letter with its Centered Headline theme. + * + * @return a {@code DocumentTemplate} for the "Centered Headline Letter" */ public static DocumentTemplate create() { return create(CvTheme.centeredHeadline()); @@ -60,6 +62,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Centered Headline Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/ClassicSerifLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/ClassicSerifLetter.java index 0368c0f9..24224d94 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/ClassicSerifLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/ClassicSerifLetter.java @@ -52,6 +52,8 @@ private ClassicSerifLetter() { /** * Builds the letter with its Classic Serif theme. + * + * @return a {@code DocumentTemplate} for the "Classic Serif Letter" */ public static DocumentTemplate create() { return create(CvTheme.classicSerif()); @@ -60,6 +62,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Classic Serif Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/CompactMonoLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/CompactMonoLetter.java index 654411df..3ac0f5a0 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/CompactMonoLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/CompactMonoLetter.java @@ -62,6 +62,8 @@ private CompactMonoLetter() { /** * Builds the letter with its Compact Mono theme. + * + * @return a {@code DocumentTemplate} for the "Compact Mono Letter" */ public static DocumentTemplate create() { return create(CvTheme.compactMono()); @@ -70,6 +72,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Compact Mono Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/EditorialBlueLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/EditorialBlueLetter.java index 24f12dac..8196da20 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/EditorialBlueLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/EditorialBlueLetter.java @@ -50,6 +50,8 @@ private EditorialBlueLetter() { /** * Builds the letter with its Editorial Blue theme. + * + * @return a {@code DocumentTemplate} for the "Editorial Blue Letter" */ public static DocumentTemplate create() { return create(CvTheme.editorialBlue()); @@ -58,6 +60,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Editorial Blue Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/EngineeringResumeLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/EngineeringResumeLetter.java index 39bfa281..f3189d47 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/EngineeringResumeLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/EngineeringResumeLetter.java @@ -72,6 +72,8 @@ private EngineeringResumeLetter() { /** * Builds the letter with its Engineering Resume theme. + * + * @return a {@code DocumentTemplate} for the "Engineering Resume Letter" */ public static DocumentTemplate create() { return create(CvTheme.engineeringResume()); @@ -80,6 +82,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Engineering Resume Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/ExecutiveLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/ExecutiveLetter.java index d2f8ee9b..f376744c 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/ExecutiveLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/ExecutiveLetter.java @@ -74,6 +74,8 @@ private ExecutiveLetter() { /** * Builds the letter with its Executive theme. + * + * @return a {@code DocumentTemplate} for the "Executive Letter" */ public static DocumentTemplate create() { return create(CvTheme.executive()); @@ -82,6 +84,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Executive Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/MintEditorialLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/MintEditorialLetter.java index 5e356fcf..7b2726be 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/MintEditorialLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/MintEditorialLetter.java @@ -74,7 +74,11 @@ public final class MintEditorialLetter { private MintEditorialLetter() { } - /** Builds the letter with its Mint Editorial theme and default colours. */ + /** + * Builds the letter with its Mint Editorial theme and default colours. + * + * @return a {@code DocumentTemplate} for the "Mint Editorial Letter" + */ public static DocumentTemplate create() { return create(CvTheme.mintEditorial(), Options.defaults()); } @@ -82,12 +86,20 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme and default colours * (share the paired CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Mint Editorial Letter" */ public static DocumentTemplate create(CvTheme theme) { return create(theme, Options.defaults()); } - /** Builds the letter with its Mint Editorial theme and explicit colours. */ + /** + * Builds the letter with its Mint Editorial theme and explicit colours. + * + * @param options masthead colour knobs (accent, rule, name, header band) + * @return a {@code DocumentTemplate} for the "Mint Editorial Letter" + */ public static DocumentTemplate create(Options options) { return create(CvTheme.mintEditorial(), options); } @@ -96,6 +108,10 @@ public static DocumentTemplate create(Options options) { * Builds the letter with a caller-supplied theme and explicit colour * {@link Options}. Pass the same {@code Options} as the paired CV preset * so the recoloured masthead matches. + * + * @param theme the active theme supplying palette, typography, and spacing + * @param options masthead colour knobs (accent, rule, name, header band) + * @return a {@code DocumentTemplate} for the "Mint Editorial Letter" */ public static DocumentTemplate create(CvTheme theme, Options options) { @@ -123,14 +139,27 @@ public record Options(DocumentColor accentColor, DocumentColor nameColor, DocumentColor headerBandColor) { + /** + * Returns options with every field {@code null} (stock render). + * + * @return default options reproducing the stock masthead + */ public static Options defaults() { return new Options(null, null, null, null); } + /** + * Creates a new options builder. + * + * @return new options builder + */ public static Builder builder() { return new Builder(); } + /** + * Mutable builder for {@link Options}. + */ public static final class Builder { private DocumentColor accentColor; private DocumentColor ruleColor; @@ -140,26 +169,55 @@ public static final class Builder { private Builder() { } + /** + * Sets the mint accent colour for the tagline. + * + * @param value accent colour; {@code null} restores the theme default + * @return this builder + */ public Builder accentColor(DocumentColor value) { this.accentColor = value; return this; } + /** + * Sets the masthead rule colour. + * + * @param value rule colour; {@code null} reuses the resolved accent + * @return this builder + */ public Builder ruleColor(DocumentColor value) { this.ruleColor = value; return this; } + /** + * Sets the masthead name colour. + * + * @param value name colour; {@code null} restores the theme default + * @return this builder + */ public Builder nameColor(DocumentColor value) { this.nameColor = value; return this; } + /** + * Sets the optional full-width band colour behind the masthead. + * + * @param value header band colour; {@code null} renders no band + * @return this builder + */ public Builder headerBandColor(DocumentColor value) { this.headerBandColor = value; return this; } + /** + * Builds an immutable {@link Options}. + * + * @return new options + */ public Options build() { return new Options(accentColor, ruleColor, nameColor, headerBandColor); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/ModernProfessionalLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/ModernProfessionalLetter.java index d2017538..d2d8168f 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/ModernProfessionalLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/ModernProfessionalLetter.java @@ -56,6 +56,8 @@ private ModernProfessionalLetter() { /** * Builds the letter with its Modern Professional theme. + * + * @return a {@code DocumentTemplate} for the "Modern Professional Letter" */ public static DocumentTemplate create() { return create(CvTheme.modernProfessional()); @@ -64,6 +66,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Modern Professional Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/MonogramSidebarLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/MonogramSidebarLetter.java index 0c4e2bbe..30285b46 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/MonogramSidebarLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/MonogramSidebarLetter.java @@ -82,6 +82,8 @@ private MonogramSidebarLetter() { /** * Builds the letter with its Monogram Sidebar theme. + * + * @return a {@code DocumentTemplate} for the "Monogram Sidebar Letter" */ public static DocumentTemplate create() { return create(CvTheme.monogramSidebar()); @@ -90,6 +92,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Monogram Sidebar Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/NordicCleanLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/NordicCleanLetter.java index 507bd092..7ead4ef5 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/NordicCleanLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/NordicCleanLetter.java @@ -54,6 +54,8 @@ private NordicCleanLetter() { /** * Builds the letter with its Nordic Clean theme. + * + * @return a {@code DocumentTemplate} for the "Nordic Clean Letter" */ public static DocumentTemplate create() { return create(CvTheme.nordicClean()); @@ -62,6 +64,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Nordic Clean Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/PanelLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/PanelLetter.java index 2db1fb80..a5a8ffa5 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/PanelLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/PanelLetter.java @@ -67,6 +67,8 @@ private PanelLetter() { /** * Builds the letter with its Panel theme. + * + * @return a {@code DocumentTemplate} for the "Panel Letter" */ public static DocumentTemplate create() { return create(CvTheme.panel()); @@ -75,6 +77,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Panel Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/SidebarPortraitLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/SidebarPortraitLetter.java index b7c2c05f..04fa00b9 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/SidebarPortraitLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/SidebarPortraitLetter.java @@ -48,6 +48,8 @@ private SidebarPortraitLetter() { /** * Builds the letter with its Sidebar Portrait theme. + * + * @return a {@code DocumentTemplate} for the "Sidebar Portrait Letter" */ public static DocumentTemplate create() { return create(CvTheme.sidebarPortrait()); @@ -56,6 +58,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Sidebar Portrait Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/TimelineMinimalLetter.java b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/TimelineMinimalLetter.java index f4341c2f..dbe81b7e 100644 --- a/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/TimelineMinimalLetter.java +++ b/src/main/java/com/demcha/compose/document/templates/coverletter/v2/presets/TimelineMinimalLetter.java @@ -78,6 +78,8 @@ private TimelineMinimalLetter() { /** * Builds the letter with its Timeline Minimal theme. + * + * @return a {@code DocumentTemplate} for the "Timeline Minimal Letter" */ public static DocumentTemplate create() { return create(CvTheme.timelineMinimal()); @@ -86,6 +88,9 @@ public static DocumentTemplate create() { /** * Builds the letter with a caller-supplied theme (share the paired * CV's theme instance for a guaranteed visual match). + * + * @param theme the active theme supplying palette, typography, and spacing + * @return a {@code DocumentTemplate} for the "Timeline Minimal Letter" */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/builder/package-info.java b/src/main/java/com/demcha/compose/document/templates/cv/builder/package-info.java index 4a9fd87c..9a719226 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/builder/package-info.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/builder/package-info.java @@ -19,11 +19,6 @@ * {@code docs/templates/v2-layered/}.

* * @since 1.6.0 - * @deprecated Superseded by the layered - * {@code com.demcha.compose.document.templates.cv.v2} surface (the - * current standard). This Gen-2 package is kept for backward - * compatibility and will be removed in a future major. See - * {@code docs/templates/v2-layered/}. */ @Deprecated(since = "1.7.0", forRemoval = true) package com.demcha.compose.document.templates.cv.builder; diff --git a/src/main/java/com/demcha/compose/document/templates/cv/layouts/package-info.java b/src/main/java/com/demcha/compose/document/templates/cv/layouts/package-info.java index a546def8..4045ea81 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/layouts/package-info.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/layouts/package-info.java @@ -30,11 +30,6 @@ * {@code docs/templates/v2-layered/}.

* * @since 1.6.0 - * @deprecated Superseded by the layered - * {@code com.demcha.compose.document.templates.cv.v2} surface (the - * current standard). This Gen-2 package is kept for backward - * compatibility and will be removed in a future major. See - * {@code docs/templates/v2-layered/}. */ @Deprecated(since = "1.7.0", forRemoval = true) package com.demcha.compose.document.templates.cv.layouts; diff --git a/src/main/java/com/demcha/compose/document/templates/cv/package-info.java b/src/main/java/com/demcha/compose/document/templates/cv/package-info.java index b4a00e9d..3575c1d1 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/package-info.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/package-info.java @@ -29,11 +29,6 @@ * {@code docs/templates/v2-layered/}.

* * @since 1.6.0 - * @deprecated Superseded by the layered - * {@code com.demcha.compose.document.templates.cv.v2} surface (the - * current standard). This Gen-2 package is kept for backward - * compatibility and will be removed in a future major. See - * {@code docs/templates/v2-layered/}. */ @Deprecated(since = "1.7.0", forRemoval = true) package com.demcha.compose.document.templates.cv; diff --git a/src/main/java/com/demcha/compose/document/templates/cv/presets/package-info.java b/src/main/java/com/demcha/compose/document/templates/cv/presets/package-info.java index daf4b0b9..48590119 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/presets/package-info.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/presets/package-info.java @@ -18,11 +18,6 @@ * {@code docs/templates/v2-layered/}.

* * @since 1.6.0 - * @deprecated Superseded by the layered - * {@code com.demcha.compose.document.templates.cv.v2} surface (the - * current standard). This Gen-2 package is kept for backward - * compatibility and will be removed in a future major. See - * {@code docs/templates/v2-layered/}. */ @Deprecated(since = "1.7.0", forRemoval = true) package com.demcha.compose.document.templates.cv.presets; diff --git a/src/main/java/com/demcha/compose/document/templates/cv/spec/package-info.java b/src/main/java/com/demcha/compose/document/templates/cv/spec/package-info.java index ecc170bb..16e39a0a 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/spec/package-info.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/spec/package-info.java @@ -28,11 +28,6 @@ * {@code docs/templates/v2-layered/}.

* * @since 1.6.0 - * @deprecated Superseded by the layered - * {@code com.demcha.compose.document.templates.cv.v2} surface (the - * current standard). This Gen-2 package is kept for backward - * compatibility and will be removed in a future major. See - * {@code docs/templates/v2-layered/}. */ @Deprecated(since = "1.7.0", forRemoval = true) package com.demcha.compose.document.templates.cv.spec; diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/BannerRenderer.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/BannerRenderer.java index 6371463f..7f85c757 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/BannerRenderer.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/BannerRenderer.java @@ -20,6 +20,9 @@ private BannerRenderer() { } /** + * @param section the section builder being populated + * @param title the section title text + * @param theme the active theme supplying palette, typography, and spacing * @deprecated delegates to {@link SectionHeader#banner}. */ @Deprecated diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ContactRenderer.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ContactRenderer.java index 1c34c900..0af091a6 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ContactRenderer.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ContactRenderer.java @@ -20,6 +20,9 @@ private ContactRenderer() { } /** + * @param section the section builder being populated + * @param identity the contact identity supplying the field values + * @param theme the active theme supplying palette, typography, and spacing * @deprecated delegates to {@link ContactLine#centered}. */ @Deprecated diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/CvTextStyles.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/CvTextStyles.java index e11571f6..b429131b 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/CvTextStyles.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/CvTextStyles.java @@ -12,6 +12,15 @@ public final class CvTextStyles { private CvTextStyles() { } + /** + * Builds a text style from the supplied font, size, decoration, and colour. + * + * @param font the font family + * @param size the font size in points + * @param decoration the text decoration (underline, strike-through, none) + * @param color the text colour + * @return a {@code DocumentTextStyle} carrying the supplied attributes + */ public static DocumentTextStyle of(FontName font, double size, DocumentTextDecoration decoration, diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/EntryCompactRenderer.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/EntryCompactRenderer.java index ded0eb85..0e2893a3 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/EntryCompactRenderer.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/EntryCompactRenderer.java @@ -17,6 +17,25 @@ public final class EntryCompactRenderer { private EntryCompactRenderer() { } + /** + * Renders title and date as a two-column row, then an optional + * subtitle line and the body paragraph beneath. + * + * @param host host section receiving the entry + * @param entry the entry supplying title, date, subtitle, and body + * @param rowName node name for the title/date row + * @param titleStyle text style for the title column + * @param dateStyle text style for the date column + * @param subtitleStyle text style for the subtitle line + * @param bodyStyle text style for the body paragraph + * @param rowSpacing horizontal spacing between the title and date columns + * @param titleWeight relative weight of the title column + * @param dateWeight relative weight of the date column + * @param subtitleMargin outer margin of the subtitle line + * @param bodyMargin outer margin of the body paragraph + * @param bodyLineSpacing extra space between wrapped body lines + * @param uppercaseTitle whether the title is upper-cased + */ public static void twoColumnTitleDateBody(SectionBuilder host, CvEntry entry, String rowName, @@ -61,6 +80,17 @@ public static void twoColumnTitleDateBody(SectionBuilder host, bodyLineSpacing, bodyMargin); } + /** + * Renders the title followed by subtitle and date appended as + * {@code " / "}-separated meta on a single line. + * + * @param host host section receiving the entry + * @param entry the entry supplying title, subtitle, and date + * @param titleStyle text style for the title + * @param metaStyle text style for the appended subtitle and date + * @param lineSpacing extra space between wrapped lines + * @param margin outer margin of the paragraph + */ public static void slashMeta(SectionBuilder host, CvEntry entry, DocumentTextStyle titleStyle, @@ -82,6 +112,18 @@ public static void slashMeta(SectionBuilder host, })); } + /** + * Renders the title followed by subtitle and date appended as + * {@code " / "}-separated meta, each in its own style. + * + * @param host host section receiving the entry + * @param entry the entry supplying title, subtitle, and date + * @param titleStyle text style for the title + * @param subtitleStyle text style for the appended subtitle + * @param dateStyle text style for the appended date + * @param lineSpacing extra space between wrapped lines + * @param margin outer margin of the paragraph + */ public static void slashSubtitleDate(SectionBuilder host, CvEntry entry, DocumentTextStyle titleStyle, @@ -104,6 +146,25 @@ public static void slashSubtitleDate(SectionBuilder host, })); } + /** + * Renders the title with the date appended inline after + * {@code datePrefix}, then an optional subtitle line and the body + * paragraph beneath. + * + * @param host host section receiving the entry + * @param entry the entry supplying title, date, subtitle, and body + * @param titleStyle text style for the title + * @param dateStyle text style for the appended date + * @param subtitleStyle text style for the subtitle line + * @param bodyStyle text style for the body paragraph + * @param datePrefix separator inserted between title and date + * @param headerLineSpacing extra space between wrapped header lines + * @param headerMargin outer margin of the title/date header + * @param subtitleMargin outer margin of the subtitle line + * @param bodyMargin outer margin of the body paragraph + * @param bodyLineSpacing extra space between wrapped body lines + * @param uppercaseTitle whether the title is upper-cased + */ public static void titleDateBody(SectionBuilder host, CvEntry entry, DocumentTextStyle titleStyle, @@ -142,6 +203,24 @@ public static void titleDateBody(SectionBuilder host, bodyLineSpacing, bodyMargin); } + /** + * Renders the title with subtitle and date appended inline after + * {@code subtitlePrefix} and {@code datePrefix}, then the body + * paragraph beneath. + * + * @param host host section receiving the entry + * @param entry the entry supplying title, subtitle, date, and body + * @param titleStyle text style for the title + * @param subtitleStyle text style for the appended subtitle + * @param dateStyle text style for the appended date + * @param bodyStyle text style for the body paragraph + * @param subtitlePrefix separator inserted before the subtitle + * @param datePrefix separator inserted before the date + * @param headerLineSpacing extra space between wrapped header lines + * @param headerMargin outer margin of the header paragraph + * @param bodyMargin outer margin of the body paragraph + * @param bodyLineSpacing extra space between wrapped body lines + */ public static void titleSubtitleDateBody(SectionBuilder host, CvEntry entry, DocumentTextStyle titleStyle, diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/EntryRenderer.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/EntryRenderer.java index eac18e02..e7e38b15 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/EntryRenderer.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/EntryRenderer.java @@ -30,6 +30,13 @@ public final class EntryRenderer { private EntryRenderer() { } + /** + * Renders one entry as the four-zone timeline row described above. + * + * @param section the section builder being populated + * @param entry the entry supplying title, date, subtitle, and body + * @param theme the active theme supplying palette, typography, and spacing + */ public static void render(SectionBuilder section, CvEntry entry, CvTheme theme) { DocumentTextStyle titleStyle = theme.entryTitleStyle(); DocumentTextStyle dateStyle = theme.entryDateStyle(); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/HeadlineRenderer.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/HeadlineRenderer.java index c5805e64..915691cc 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/HeadlineRenderer.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/HeadlineRenderer.java @@ -20,6 +20,9 @@ private HeadlineRenderer() { } /** + * @param section the section builder being populated + * @param name the candidate name to render as the headline + * @param theme the active theme supplying palette, typography, and spacing * @deprecated delegates to {@link Headline#spacedCentered}. */ @Deprecated diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/LabelValueRenderer.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/LabelValueRenderer.java index 3f9a7386..613d1d45 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/LabelValueRenderer.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/LabelValueRenderer.java @@ -12,6 +12,18 @@ public final class LabelValueRenderer { private LabelValueRenderer() { } + /** + * Renders one {@code "Label: value"} row, with the value parsed as + * inline markdown. + * + * @param host host section receiving the row + * @param label the label text; a trailing colon is normalised away + * @param value the value text; blank values render the label alone + * @param labelStyle text style for the label + * @param valueStyle text style for the value + * @param lineSpacing extra space between wrapped lines + * @param margin outer margin of the paragraph + */ public static void render(SectionBuilder host, String label, String value, diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ParagraphRenderer.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ParagraphRenderer.java index 99a3a03e..82743339 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ParagraphRenderer.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ParagraphRenderer.java @@ -18,6 +18,8 @@ private ParagraphRenderer() { } /** + * Renders one body-style prose paragraph into the host section. + * * @param section host * @param text paragraph text; blank inputs are silently skipped * @param theme active theme diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ProjectLabel.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ProjectLabel.java index c94a2354..d5c88766 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ProjectLabel.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ProjectLabel.java @@ -20,6 +20,9 @@ * fragment) is always plain text — link syntax inside the stack is not * supported because the regex requires the stack content to contain * no parentheses.

+ * + * @param title the display title, with inline Markdown syntax preserved + * @param stack the parenthesised technology stack as plain text */ public record ProjectLabel(String title, String stack) { @@ -32,6 +35,7 @@ public record ProjectLabel(String title, String stack) { private static final Pattern TRAILING_STACK = Pattern.compile("\\s+\\(([^()]*)\\)\\s*$"); + /** Normalises null title and stack to empty strings. */ public ProjectLabel { title = title == null ? "" : title; stack = stack == null ? "" : stack; diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ProjectRenderer.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ProjectRenderer.java index cfd9ff9e..b1333906 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ProjectRenderer.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/ProjectRenderer.java @@ -22,6 +22,18 @@ public final class ProjectRenderer { private ProjectRenderer() { } + /** + * Renders the project title (link-aware), optional stack, and body + * inline on a single paragraph. + * + * @param host host section receiving the row + * @param row the row supplying the label and body + * @param titleStyle text style for the parsed title + * @param stackStyle text style for the parenthesised stack + * @param bodyStyle text style for the trailing body + * @param lineSpacing extra space between wrapped lines + * @param margin outer margin of the paragraph + */ public static void inline(SectionBuilder host, CvRow row, DocumentTextStyle titleStyle, @@ -47,6 +59,18 @@ public static void inline(SectionBuilder host, })); } + /** + * Renders the label as plain text (dropping link syntax) and the + * body inline on a single line, separated by {@code delimiter}. + * + * @param host host section receiving the row + * @param row the row supplying the label and body + * @param labelStyle text style for the plain-text label + * @param bodyStyle text style for the trailing body + * @param lineSpacing extra space between wrapped lines + * @param margin outer margin of the paragraph + * @param delimiter separator inserted between label and body + */ public static void plainInline(SectionBuilder host, CvRow row, DocumentTextStyle labelStyle, @@ -73,6 +97,19 @@ public static void plainInline(SectionBuilder host, })); } + /** + * Renders the project title (link-aware) and optional stack on + * their own paragraph, then the body paragraph beneath. + * + * @param host host section receiving the row + * @param row the row supplying the label and body + * @param titleStyle text style for the parsed title + * @param stackStyle text style for the parenthesised stack + * @param bodyStyle text style for the body paragraph + * @param bodyLineSpacing extra space between wrapped body lines + * @param titleMargin outer margin of the title paragraph + * @param bodyMargin outer margin of the body paragraph + */ public static void titleThenBody(SectionBuilder host, CvRow row, DocumentTextStyle titleStyle, diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/RichParagraphRenderer.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/RichParagraphRenderer.java index 8e39de00..3681cc1d 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/RichParagraphRenderer.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/RichParagraphRenderer.java @@ -13,6 +13,16 @@ public final class RichParagraphRenderer { private RichParagraphRenderer() { } + /** + * Renders a left-aligned rich paragraph with the supplied style, + * line spacing, and margin. + * + * @param host host section receiving the paragraph + * @param text paragraph text; null or blank inputs are skipped + * @param style base text style + * @param lineSpacing extra space between wrapped lines + * @param margin outer margin of the paragraph + */ public static void render(SectionBuilder host, String text, DocumentTextStyle style, @@ -21,6 +31,17 @@ public static void render(SectionBuilder host, render(host, text, style, lineSpacing, margin, TextAlign.LEFT); } + /** + * Renders a rich paragraph with explicit alignment, style, line + * spacing, and margin. + * + * @param host host section receiving the paragraph + * @param text paragraph text; null or blank inputs are skipped + * @param style base text style + * @param lineSpacing extra space between wrapped lines + * @param margin outer margin of the paragraph + * @param align horizontal text alignment + */ public static void render(SectionBuilder host, String text, DocumentTextStyle style, diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SectionDispatcher.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SectionDispatcher.java index 7045447f..2c759c79 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SectionDispatcher.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SectionDispatcher.java @@ -30,6 +30,15 @@ public final class SectionDispatcher { private SectionDispatcher() { } + /** + * Renders the section body into the host, dispatching on the + * sealed {@link CvSection} subtype. + * + * @param host host section receiving the body + * @param section the section whose subtype selects the renderer + * @param theme the active theme supplying palette, typography, and spacing + * @throws IllegalStateException if the section subtype is unhandled + */ public static void renderBody(SectionBuilder host, CvSection section, CvTheme theme) { host.spacing(theme.spacing().sectionBodySpacing()) .padding(theme.spacing().sectionBodyPadding()); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SectionLookup.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SectionLookup.java index befa05ac..9543e4a5 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SectionLookup.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SectionLookup.java @@ -15,6 +15,14 @@ public final class SectionLookup { private SectionLookup() { } + /** + * Returns the first section whose normalised title contains any of + * the normalised keys. + * + * @param sections the sections to scan; null yields {@code null} + * @param keys the candidate title fragments; null yields {@code null} + * @return the first matching section, or {@code null} if none match + */ public static CvSection firstMatching(List sections, List keys) { if (sections == null || keys == null) { @@ -35,6 +43,13 @@ public static CvSection firstMatching(List sections, return null; } + /** + * Reports whether the section carries any renderable content. + * + * @param section the section to inspect + * @return {@code true} if the section has non-empty body, entries, + * rows, or skill groups + */ public static boolean hasContent(CvSection section) { if (section instanceof ParagraphSection paragraph) { return paragraph.body() != null && !paragraph.body().isBlank(); @@ -51,10 +66,23 @@ public static boolean hasContent(CvSection section) { return false; } + /** + * Reports whether the normalised title contains the normalised key. + * + * @param title the title to test + * @param key the fragment to look for + * @return {@code true} if the normalised title contains the normalised key + */ public static boolean titleContains(String title, String key) { return normalize(title).contains(normalize(key)); } + /** + * Normalises a value to lower-case alphanumerics for loose matching. + * + * @param value the value to normalise; null yields an empty string + * @return the lower-cased value with non-alphanumeric characters removed + */ public static String normalize(String value) { return value == null ? "" : value.toLowerCase().replaceAll("[^a-z0-9]+", ""); } diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SkillLineRenderer.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SkillLineRenderer.java index a92d65da..75c73826 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SkillLineRenderer.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SkillLineRenderer.java @@ -16,6 +16,19 @@ public final class SkillLineRenderer { private SkillLineRenderer() { } + /** + * Renders one skill category as a single line, listing up to + * {@code limit} skills after the bolded category label. + * + * @param host host section receiving the line + * @param group the skill group supplying the category and skills + * @param limit maximum number of skills to list + * @param labelStyle text style for the category label + * @param valueStyle text style for the joined skills + * @param lineSpacing extra space between wrapped lines + * @param margin outer margin of the paragraph + * @param labelSuffix text appended after the category label + */ public static void limitedInline(SectionBuilder host, SkillGroup group, int limit, diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SkillTableRenderer.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SkillTableRenderer.java index 896635d5..09ae948c 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SkillTableRenderer.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SkillTableRenderer.java @@ -16,6 +16,16 @@ public final class SkillTableRenderer { private SkillTableRenderer() { } + /** + * Renders all skills across the groups as a flat grid, optionally + * prefixing each cell with a bullet. + * + * @param host host section receiving the grid + * @param groups the skill groups whose skills are flattened + * @param width available grid width in points + * @param style visual table options + * @param bulletPrefix text prepended to each skill cell; null means none + */ public static void grid(SectionBuilder host, List groups, double width, diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SkillsRenderer.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SkillsRenderer.java index 47c034af..87abfca0 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SkillsRenderer.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/components/SkillsRenderer.java @@ -22,6 +22,14 @@ public final class SkillsRenderer { private SkillsRenderer() { } + /** + * Renders each skill group as one bulleted paragraph with the + * category bolded and its skills joined inline. + * + * @param section the section builder being populated + * @param skills the grouped skills to render + * @param theme the active theme supplying palette, typography, and spacing + */ public static void render(SectionBuilder section, SkillsSection skills, CvTheme theme) { diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvContact.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvContact.java index cce85679..3db3cbd6 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvContact.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvContact.java @@ -15,6 +15,7 @@ */ public record CvContact(String phone, String email, String address) { + /** Validates that every field is non-null and non-blank. */ public CvContact { Objects.requireNonNull(phone, "phone"); Objects.requireNonNull(email, "email"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvDocument.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvDocument.java index bd214778..7205f4cd 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvDocument.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvDocument.java @@ -24,6 +24,10 @@ */ public record CvDocument(CvIdentity identity, List placements) { + /** + * Validates that {@code identity} and {@code placements} are + * non-null and defensively copies the placement list. + */ public CvDocument { Objects.requireNonNull(identity, "identity"); Objects.requireNonNull(placements, "placements"); @@ -43,6 +47,11 @@ public record CvDocument(CvIdentity identity, List placements) { * multi-column presets need explicit slot placement that the * builder makes obvious at the call site.

* + * @param identity required identity / contact block + * @param sections sections to wrap, each in a {@link Slot#MAIN} + * placement, in source order + * @return a {@code CvDocument} with every section placed in + * {@link Slot#MAIN} * @deprecated since the slot model — prefer the {@link Builder} * so non-MAIN slots are visible at the call site. */ @@ -60,6 +69,7 @@ public static CvDocument ofMainSections(CvIdentity identity, */ public record Placement(Slot slot, CvSection section) { + /** Validates that both fields are non-null. */ public Placement { Objects.requireNonNull(slot, "slot"); Objects.requireNonNull(section, "section"); @@ -128,6 +138,8 @@ public Slot slotOf(CvSection section) { // -- builder --------------------------------------------------------- /** + * Creates a fluent builder for {@code CvDocument}. + * * @return new fluent builder */ public static Builder builder() { @@ -149,6 +161,12 @@ public static final class Builder { private Builder() { } + /** + * Sets the required identity block. + * + * @param value the identity block to use + * @return this builder for chaining + */ public Builder identity(CvIdentity value) { this.identity = value; return this; @@ -156,6 +174,9 @@ public Builder identity(CvIdentity value) { /** * Appends one section into {@link Slot#MAIN}. + * + * @param section section to append + * @return this builder for chaining */ public Builder section(CvSection section) { return section(Slot.MAIN, section); @@ -163,6 +184,10 @@ public Builder section(CvSection section) { /** * Appends one section into a chosen slot. + * + * @param slot placement region + * @param section section to append + * @return this builder for chaining */ public Builder section(Slot slot, CvSection section) { this.placements.add(new Placement(slot, section)); @@ -172,6 +197,9 @@ public Builder section(Slot slot, CvSection section) { /** * Varargs convenience — all sections placed in * {@link Slot#MAIN}. + * + * @param values sections to append, in source order + * @return this builder for chaining */ public Builder sections(CvSection... values) { Objects.requireNonNull(values, "values"); @@ -184,6 +212,10 @@ public Builder sections(CvSection... values) { /** * Varargs convenience — all supplied sections placed in * {@code slot}. + * + * @param slot placement region for every supplied section + * @param values sections to append, in source order + * @return this builder for chaining */ public Builder sections(Slot slot, CvSection... values) { Objects.requireNonNull(slot, "slot"); @@ -196,6 +228,9 @@ public Builder sections(Slot slot, CvSection... values) { /** * List variant — all sections placed in {@link Slot#MAIN}. + * + * @param values sections to append, in source order + * @return this builder for chaining */ public Builder sections(List values) { Objects.requireNonNull(values, "values"); @@ -207,12 +242,20 @@ public Builder sections(List values) { /** * Appends a pre-built {@link Placement}. + * + * @param placement the placement to append (non-null) + * @return this builder for chaining */ public Builder placement(Placement placement) { this.placements.add(Objects.requireNonNull(placement, "placement")); return this; } + /** + * Builds the immutable {@link CvDocument}. + * + * @return the assembled document + */ public CvDocument build() { return new CvDocument(identity, placements); } diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvEntry.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvEntry.java index 5a07b557..2985658e 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvEntry.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvEntry.java @@ -22,6 +22,7 @@ */ public record CvEntry(String title, String subtitle, String date, String body) { + /** Validates that every field is non-null and that {@code title} is non-blank. */ public CvEntry { Objects.requireNonNull(title, "title"); Objects.requireNonNull(subtitle, "subtitle"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvIdentity.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvIdentity.java index 715c993f..b5b3c776 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvIdentity.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvIdentity.java @@ -24,6 +24,11 @@ public record CvIdentity(CvName name, String jobTitle, CvContact contact, List links) { + /** + * Validates that {@code name} and {@code contact} are non-null, + * trims a null {@code jobTitle} to empty, and defensively copies + * {@code links} (null becomes an empty list). + */ public CvIdentity { Objects.requireNonNull(name, "name"); jobTitle = jobTitle == null ? "" : jobTitle.trim(); @@ -34,12 +39,19 @@ public record CvIdentity(CvName name, String jobTitle, /** * Backward-compatible constructor for callers that predate the * optional job-title field. The title simply stays blank. + * + * @param name structured name with first / last required and an + * optional middle component + * @param contact phone / email / address — all three required + * @param links ordered list of optional outbound links; never null */ public CvIdentity(CvName name, CvContact contact, List links) { this(name, "", contact, links); } /** + * Creates a fluent builder for {@code CvIdentity}. + * * @return new fluent builder */ public static Builder builder() { @@ -58,16 +70,37 @@ public static final class Builder { private Builder() { } + /** + * Sets the structured name. + * + * @param value the name to use + * @return this builder for chaining + */ public Builder name(CvName value) { this.name = value; return this; } + /** + * Sets the name from first and last parts. + * + * @param first first name (required, non-blank) + * @param last family name (required, non-blank) + * @return this builder for chaining + */ public Builder name(String first, String last) { this.name = CvName.of(first, last); return this; } + /** + * Sets the name from first, middle, and last parts. + * + * @param first first name (required, non-blank) + * @param middle optional middle name; may be empty + * @param last family name (required, non-blank) + * @return this builder for chaining + */ public Builder name(String first, String middle, String last) { this.name = new CvName(first, middle, last); return this; @@ -76,32 +109,67 @@ public Builder name(String first, String middle, String last) { /** * Sets the optional professional title shown only by presets * with a dedicated subtitle/header line. + * + * @param value the professional title; null becomes empty + * @return this builder for chaining */ public Builder jobTitle(String value) { this.jobTitle = value == null ? "" : value; return this; } + /** + * Sets the contact block. + * + * @param value the contact block to use + * @return this builder for chaining + */ public Builder contact(CvContact value) { this.contact = value; return this; } + /** + * Sets the contact block from its three required fields. + * + * @param phone non-blank phone number + * @param email non-blank email address + * @param address non-blank location / postal address line + * @return this builder for chaining + */ public Builder contact(String phone, String email, String address) { this.contact = new CvContact(phone, email, address); return this; } + /** + * Appends one outbound link. + * + * @param link the link to append (non-null) + * @return this builder for chaining + */ public Builder link(CvLink link) { this.links.add(Objects.requireNonNull(link, "link")); return this; } + /** + * Appends one outbound link from its label and target. + * + * @param label visible link text (required, non-blank) + * @param url click target (required, non-blank) + * @return this builder for chaining + */ public Builder link(String label, String url) { this.links.add(new CvLink(label, url)); return this; } + /** + * Builds the immutable {@link CvIdentity}. + * + * @return the assembled identity block + */ public CvIdentity build() { return new CvIdentity(name, jobTitle, contact, links); } diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvLink.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvLink.java index 5e365ad7..95ef2196 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvLink.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvLink.java @@ -11,6 +11,7 @@ */ public record CvLink(String label, String url) { + /** Validates that both fields are non-null and non-blank. */ public CvLink { Objects.requireNonNull(label, "label"); Objects.requireNonNull(url, "url"); @@ -25,6 +26,10 @@ public record CvLink(String label, String url) { /** * Convenience factory mirroring {@code CvLink.of("LinkedIn", * "https://...")} call sites. + * + * @param label visible link text (required, non-blank) + * @param url click target (required, non-blank) + * @return a {@code CvLink} with the given label and target */ public static CvLink of(String label, String url) { return new CvLink(label, url); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvName.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvName.java index 34203436..60cd25f9 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvName.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvName.java @@ -17,6 +17,10 @@ */ public record CvName(String first, String middle, String last) { + /** + * Validates that {@code first} and {@code last} are non-null and + * non-blank, and normalises a null {@code middle} to empty. + */ public CvName { Objects.requireNonNull(first, "first"); Objects.requireNonNull(last, "last"); @@ -31,12 +35,18 @@ public record CvName(String first, String middle, String last) { /** * Convenience constructor for the common first + last case. + * + * @param first first name (required, non-blank) + * @param last family name (required, non-blank) + * @return a {@code CvName} with an empty middle component */ public static CvName of(String first, String last) { return new CvName(first, "", last); } /** + * Optional middle component, absent when blank. + * * @return middle wrapped in {@link Optional#empty()} when blank, * otherwise the middle name */ @@ -47,6 +57,8 @@ public Optional middleName() { /** * Concatenates the present parts with single spaces in * first / middle / last order. + * + * @return the full name, middle part included only when present */ public String full() { return middle.isBlank() diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvRow.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvRow.java index 59773e75..1d810c99 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvRow.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvRow.java @@ -21,6 +21,7 @@ */ public record CvRow(String label, String body) { + /** Validates that every field is non-null and that {@code label} is non-blank. */ public CvRow { Objects.requireNonNull(label, "label"); Objects.requireNonNull(body, "body"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvSection.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvSection.java index 97d81037..028358d4 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvSection.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvSection.java @@ -26,6 +26,8 @@ public sealed interface CvSection permits ParagraphSection, RowsSection, EntriesSection, SkillsSection { /** + * Banner heading shown above this section's body. + * * @return banner heading shown above the body (non-blank by * construction) */ diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvSkill.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvSkill.java index 4e90c6d4..b1797e64 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvSkill.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/CvSkill.java @@ -21,6 +21,11 @@ */ public record CvSkill(String name, OptionalDouble level) { + /** + * Validates that both fields are non-null, trims {@code name} and + * rejects a blank result, and bounds any present {@code level} to + * {@code [0, 1]}. + */ public CvSkill { Objects.requireNonNull(name, "name"); Objects.requireNonNull(level, "level"); @@ -37,12 +42,23 @@ public record CvSkill(String name, OptionalDouble level) { } } - /** Skill with no proficiency level. */ + /** + * Skill with no proficiency level. + * + * @param name non-blank skill label + * @return a {@code CvSkill} carrying an empty level + */ public static CvSkill of(String name) { return new CvSkill(name, OptionalDouble.empty()); } - /** Skill with a proficiency level, clamped to {@code [0, 1]}. */ + /** + * Skill with a proficiency level, clamped to {@code [0, 1]}. + * + * @param name non-blank skill label + * @param level proficiency, clamped into {@code [0, 1]} + * @return a {@code CvSkill} carrying the clamped level + */ public static CvSkill of(String name, double level) { return new CvSkill(name, OptionalDouble.of(Math.max(0.0, Math.min(1.0, level)))); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/EntriesSection.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/EntriesSection.java index 55beebc3..32675185 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/EntriesSection.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/EntriesSection.java @@ -20,6 +20,10 @@ public record EntriesSection(String title, List entries) implements CvSection { + /** + * Validates that {@code title} and {@code entries} are non-null, + * rejects a blank title, and defensively copies the entry list. + */ public EntriesSection { Objects.requireNonNull(title, "title"); Objects.requireNonNull(entries, "entries"); @@ -50,16 +54,38 @@ private Builder(String title) { this.title = title; } + /** + * Appends one entry built from its four fields. + * + * @param title bold heading (job title, degree) + * @param subtitle italic subtitle (employer, institution); + * blank collapses the subtitle line + * @param date right-aligned date column; blank removes it + * @param body full-width prose paragraph; may contain + * inline markdown + * @return this builder for chaining + */ public Builder entry(String title, String subtitle, String date, String body) { this.entries.add(new CvEntry(title, subtitle, date, body)); return this; } + /** + * Appends one pre-built entry. + * + * @param entry the entry to append (non-null) + * @return this builder for chaining + */ public Builder entry(CvEntry entry) { this.entries.add(Objects.requireNonNull(entry, "entry")); return this; } + /** + * Builds the immutable {@link EntriesSection}. + * + * @return the assembled section + */ public EntriesSection build() { return new EntriesSection(title, entries); } diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/ParagraphSection.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/ParagraphSection.java index a635d85d..a12259b1 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/ParagraphSection.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/ParagraphSection.java @@ -15,6 +15,7 @@ */ public record ParagraphSection(String title, String body) implements CvSection { + /** Validates that every field is non-null and that {@code title} is non-blank. */ public ParagraphSection { Objects.requireNonNull(title, "title"); Objects.requireNonNull(body, "body"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/RowsSection.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/RowsSection.java index e4e4b685..3a186085 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/RowsSection.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/RowsSection.java @@ -28,6 +28,11 @@ public record RowsSection(String title, List rows, RowStyle style) implements CvSection { + /** + * Validates that {@code title}, {@code rows}, and {@code style} + * are non-null, rejects a blank title, and defensively copies the + * row list. + */ public RowsSection { Objects.requireNonNull(title, "title"); Objects.requireNonNull(rows, "rows"); @@ -62,16 +67,34 @@ private Builder(String title, RowStyle style) { this.style = style; } + /** + * Appends one row built from its label and body. + * + * @param label bold key (required, non-blank) + * @param body free-form text; may contain inline markdown + * @return this builder for chaining + */ public Builder row(String label, String body) { this.rows.add(new CvRow(label, body)); return this; } + /** + * Appends one pre-built row. + * + * @param row the row to append (non-null) + * @return this builder for chaining + */ public Builder row(CvRow row) { this.rows.add(Objects.requireNonNull(row, "row")); return this; } + /** + * Builds the immutable {@link RowsSection}. + * + * @return the assembled section + */ public RowsSection build() { return new RowsSection(title, rows, style); } diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/SkillGroup.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/SkillGroup.java index b22a6441..50021ffb 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/SkillGroup.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/SkillGroup.java @@ -26,6 +26,11 @@ */ public record SkillGroup(String category, List entries) { + /** + * Validates that {@code category} and {@code entries} are + * non-null, trims and rejects a blank category, and drops any + * null or blank-named entries before copying the list. + */ public SkillGroup { Objects.requireNonNull(category, "category"); Objects.requireNonNull(entries, "entries"); @@ -42,13 +47,25 @@ public record SkillGroup(String category, List entries) { entries = List.copyOf(cleaned); } - /** Skill group from plain labels (no proficiency levels). */ + /** + * Skill group from plain labels (no proficiency levels). + * + * @param category category label, non-blank + * @param skills plain skill labels; null or blank labels are ignored + * @return a {@code SkillGroup} whose entries carry no level + */ public static SkillGroup of(String category, String... skills) { return ofNames(category, skills == null ? List.of() : Arrays.asList(skills)); } - /** Skill group from a list of plain labels (no proficiency levels). */ + /** + * Skill group from a list of plain labels (no proficiency levels). + * + * @param category category label, non-blank + * @param skills plain skill labels; null or blank labels are ignored + * @return a {@code SkillGroup} whose entries carry no level + */ public static SkillGroup ofNames(String category, List skills) { List out = new ArrayList<>(skills == null ? 0 : skills.size()); if (skills != null) { @@ -79,6 +96,8 @@ public List skills() { } /** + * Joins the skill labels into one comma-separated string. + * * @return comma-separated skill labels, useful for compact renderers */ public String skillsInline() { diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/SkillsSection.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/SkillsSection.java index ed4cea06..ed3487cd 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/data/SkillsSection.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/data/SkillsSection.java @@ -19,6 +19,11 @@ public record SkillsSection(String title, List groups) implements CvSection { + /** + * Validates that {@code title} and {@code groups} are non-null, + * rejects a blank title, and drops any null or empty groups before + * copying the list. + */ public SkillsSection { Objects.requireNonNull(title, "title"); Objects.requireNonNull(groups, "groups"); @@ -36,11 +41,21 @@ public record SkillsSection(String title, List groups) /** * Fluent builder for callers that assemble skills one by one. + * + * @param title non-blank section heading + * @return new builder */ public static Builder builder(String title) { return new Builder(title); } + /** + * Section assembled from a fixed set of skill groups. + * + * @param title non-blank section heading + * @param groups skill groups, in source order; null becomes empty + * @return a {@code SkillsSection} carrying the supplied groups + */ public static SkillsSection of(String title, SkillGroup... groups) { if (groups == null) { return new SkillsSection(title, List.of()); @@ -59,16 +74,37 @@ private Builder(String title) { this.title = title; } + /** + * Appends one pre-built skill group. + * + * @param group the group to append (non-null) + * @return this builder for chaining + */ public Builder group(SkillGroup group) { this.groups.add(Objects.requireNonNull(group, "group")); return this; } + /** + * Appends a group from a category label and a list of plain + * skill labels. + * + * @param category group category label, non-blank + * @param skills plain skill labels; null or blank labels are ignored + * @return this builder for chaining + */ public Builder group(String category, List skills) { this.groups.add(SkillGroup.ofNames(category, skills)); return this; } + /** + * Appends a group from a category label and plain skill labels. + * + * @param category group category label, non-blank + * @param skills plain skill labels; null or blank labels are ignored + * @return this builder for chaining + */ public Builder group(String category, String... skills) { this.groups.add(SkillGroup.of(category, skills)); return this; @@ -88,6 +124,11 @@ public Builder leveledGroup(String category, List entries) { return this; } + /** + * Builds the immutable {@link SkillsSection}. + * + * @return the assembled section + */ public SkillsSection build() { return new SkillsSection(title, groups); } diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/BlueBanner.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/BlueBanner.java index c1fee506..23fd6ba3 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/BlueBanner.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/BlueBanner.java @@ -80,6 +80,8 @@ private BlueBanner() { /** * Builds the preset with the Blue Banner theme. + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.blueBanner()); @@ -89,6 +91,9 @@ public static DocumentTemplate create() { * Builds the preset with a caller-supplied theme. The caller can * adjust palette, typography, spacing, or separator tokens without * changing the page-flow composition. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/CenteredHeadline.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/CenteredHeadline.java index 21d175d5..517ac944 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/CenteredHeadline.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/CenteredHeadline.java @@ -86,6 +86,8 @@ private CenteredHeadline() { /** * Builds the preset with the classic Centered Headline theme * ({@link CvTheme#centeredHeadline()}). + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.centeredHeadline()); @@ -96,6 +98,9 @@ public static DocumentTemplate create() { * variations on the Centered Headline theme (alternate * typography, slightly different palette) without forking this * class. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/ClassicSerif.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/ClassicSerif.java index 35d97ca1..76ecf844 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/ClassicSerif.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/ClassicSerif.java @@ -79,6 +79,8 @@ private ClassicSerif() { /** * Builds the preset with its Classic Serif theme. + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.classicSerif()); @@ -86,6 +88,9 @@ public static DocumentTemplate create() { /** * Builds the preset with a caller-supplied theme. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/CompactMono.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/CompactMono.java index d58bf4fd..ed6b07c3 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/CompactMono.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/CompactMono.java @@ -96,6 +96,8 @@ private CompactMono() { /** * Builds the preset with its Compact Mono theme. + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.compactMono()); @@ -105,6 +107,9 @@ public static DocumentTemplate create() { * Builds the preset with a caller-supplied theme. Use this for * controlled typography/spacing/palette variants without changing * the shipped preset. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/EditorialBlue.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/EditorialBlue.java index fb54ee09..8233050b 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/EditorialBlue.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/EditorialBlue.java @@ -75,6 +75,8 @@ private EditorialBlue() { /** * Builds the preset with its Editorial Blue theme. + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.editorialBlue()); @@ -82,6 +84,9 @@ public static DocumentTemplate create() { /** * Builds the preset with a caller-supplied theme. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/EngineeringResume.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/EngineeringResume.java index 5222019d..8722814a 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/EngineeringResume.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/EngineeringResume.java @@ -121,6 +121,8 @@ private EngineeringResume() { /** * Builds the preset with its Engineering Resume theme. + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.engineeringResume()); @@ -128,6 +130,9 @@ public static DocumentTemplate create() { /** * Builds the preset with a caller-supplied theme. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/Executive.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/Executive.java index 88296e5c..4ec35d8f 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/Executive.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/Executive.java @@ -74,6 +74,8 @@ private Executive() { /** * Builds the preset with its Executive theme. + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.executive()); @@ -81,6 +83,9 @@ public static DocumentTemplate create() { /** * Builds the preset with a caller-supplied theme. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/MinimalUnderlined.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/MinimalUnderlined.java index f7524465..5b67ce36 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/MinimalUnderlined.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/MinimalUnderlined.java @@ -58,6 +58,8 @@ private MinimalUnderlined() { /** * Builds the preset with the classic theme. + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.boxedClassic()); @@ -65,6 +67,9 @@ public static DocumentTemplate create() { /** * Builds the preset with a caller-supplied theme. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/MintEditorial.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/MintEditorial.java index 053422e1..b6a24c12 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/MintEditorial.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/MintEditorial.java @@ -229,7 +229,11 @@ public final class MintEditorial { private MintEditorial() { } - /** Builds the preset with its Mint Editorial theme and default colours. */ + /** + * Builds the preset with its Mint Editorial theme and default colours. + * + * @return ready-to-use template + */ public static DocumentTemplate create() { return create(CvTheme.mintEditorial(), Options.defaults()); } @@ -238,6 +242,9 @@ public static DocumentTemplate create() { * Builds the preset with a caller-supplied theme and default colours * (share the paired cover letter's theme instance for a guaranteed * visual match). + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { return create(theme, Options.defaults()); @@ -246,6 +253,9 @@ public static DocumentTemplate create(CvTheme theme) { /** * Builds the preset with its Mint Editorial theme and explicit colour * {@link Options}. + * + * @param options masthead colour options + * @return ready-to-use template */ public static DocumentTemplate create(Options options) { return create(CvTheme.mintEditorial(), options); @@ -255,6 +265,10 @@ public static DocumentTemplate create(Options options) { * Builds the preset with a caller-supplied theme and explicit colour * {@link Options}. Use this to recolour the masthead (accent, rule, * name, optional header band) without forking the theme. + * + * @param theme active theme + * @param options masthead colour options + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme, Options options) { @@ -285,14 +299,27 @@ public record Options(DocumentColor accentColor, DocumentColor nameColor, DocumentColor headerBandColor) { + /** + * Default options: every knob unset, reproducing the stock render. + * + * @return options that leave the committed look unchanged + */ public static Options defaults() { return new Options(null, null, null, null); } + /** + * Starts a mutable builder for the masthead colour knobs. + * + * @return new builder + */ public static Builder builder() { return new Builder(); } + /** + * Builder for {@link Options}. + */ public static final class Builder { private DocumentColor accentColor; private DocumentColor ruleColor; @@ -302,26 +329,55 @@ public static final class Builder { private Builder() { } + /** + * Sets the mint accent for the tagline and section headings. + * + * @param value accent colour + * @return this builder + */ public Builder accentColor(DocumentColor value) { this.accentColor = value; return this; } + /** + * Sets the full-width masthead rule colour. + * + * @param value rule colour + * @return this builder + */ public Builder ruleColor(DocumentColor value) { this.ruleColor = value; return this; } + /** + * Sets the masthead name text colour. + * + * @param value name colour + * @return this builder + */ public Builder nameColor(DocumentColor value) { this.nameColor = value; return this; } + /** + * Sets the optional page-1 header band colour. + * + * @param value header band colour + * @return this builder + */ public Builder headerBandColor(DocumentColor value) { this.headerBandColor = value; return this; } + /** + * Builds the configured options. + * + * @return a new {@link Options} with the configured colours + */ public Options build() { return new Options(accentColor, ruleColor, nameColor, headerBandColor); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/ModernProfessional.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/ModernProfessional.java index 1e1346b6..699681f2 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/ModernProfessional.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/ModernProfessional.java @@ -77,6 +77,8 @@ private ModernProfessional() { /** * Builds the preset with the Modern Professional theme * ({@link CvTheme#modernProfessional()}). + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.modernProfessional()); @@ -86,6 +88,9 @@ public static DocumentTemplate create() { * Builds the preset with a caller-supplied theme. Allows * variations on the Modern Professional theme (different * typography scale, custom spacing) without forking this class. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/MonogramSidebar.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/MonogramSidebar.java index f72b70c0..74692ea2 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/MonogramSidebar.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/MonogramSidebar.java @@ -139,6 +139,8 @@ private MonogramSidebar() { * Builds the preset with its Monogram Sidebar theme and default * options (theme's banner fill for the sidebar, muted-gold accent, * dark slate monogram ring). + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.monogramSidebar(), Options.defaults()); @@ -147,6 +149,9 @@ public static DocumentTemplate create() { /** * Builds the preset with a caller-supplied theme and default * options. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { return create(theme, Options.defaults()); @@ -156,6 +161,10 @@ public static DocumentTemplate create(CvTheme theme) { * Builds the preset with explicit colour options. Use this to * override the sidebar fill, accent colour, or monogram ring * without forking the theme. + * + * @param theme active theme + * @param options sidebar colour options + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme, Options options) { @@ -185,14 +194,28 @@ public record Options(DocumentColor sidebarFillColor, DocumentColor accentColor, DocumentColor monogramRingColor) { + /** + * Default options: every field unset, falling back to the theme + * palette / V1 defaults. + * + * @return options that leave the committed look unchanged + */ public static Options defaults() { return new Options(null, null, null, null); } + /** + * Starts a mutable builder for the sidebar colour knobs. + * + * @return new builder + */ public static Builder builder() { return new Builder(); } + /** + * Builder for {@link Options}. + */ public static final class Builder { private DocumentColor sidebarFillColor; private DocumentColor mainFillColor; @@ -202,26 +225,55 @@ public static final class Builder { private Builder() { } + /** + * Sets the sidebar (left column) background fill. + * + * @param value sidebar fill colour + * @return this builder + */ public Builder sidebarFillColor(DocumentColor value) { this.sidebarFillColor = value; return this; } + /** + * Sets the main (right column) background fill. + * + * @param value main fill colour + * @return this builder + */ public Builder mainFillColor(DocumentColor value) { this.mainFillColor = value; return this; } + /** + * Sets the muted-gold accent for the subtitle and dates. + * + * @param value accent colour + * @return this builder + */ public Builder accentColor(DocumentColor value) { this.accentColor = value; return this; } + /** + * Sets the monogram ring stroke and initials colour. + * + * @param value monogram ring colour + * @return this builder + */ public Builder monogramRingColor(DocumentColor value) { this.monogramRingColor = value; return this; } + /** + * Builds the configured options. + * + * @return a new {@link Options} with the configured colours + */ public Options build() { return new Options(sidebarFillColor, mainFillColor, accentColor, monogramRingColor); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/NordicClean.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/NordicClean.java index 4e64e879..74b0e0ab 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/NordicClean.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/NordicClean.java @@ -101,6 +101,8 @@ private NordicClean() { /** * Builds the preset with its Nordic Clean theme. + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.nordicClean(), Options.defaults()); @@ -108,6 +110,9 @@ public static DocumentTemplate create() { /** * Builds the preset with a caller-supplied theme. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { return create(theme, Options.defaults()); @@ -116,6 +121,10 @@ public static DocumentTemplate create(CvTheme theme) { /** * Builds the preset with a caller-supplied theme and explicit * Nordic-specific layout/colour options. + * + * @param theme active theme + * @param options Nordic-specific layout and colour options + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme, Options options) { @@ -152,6 +161,7 @@ public record Options(RailSide railSide, DocumentColor railFillColor, DocumentColor profileFillColor) { + /** Normalises null rail side, accent, and rail fill to their defaults. */ public Options { railSide = railSide == null ? RailSide.LEFT : railSide; accentColor = accentColor == null ? DEFAULT_ACCENT : accentColor; @@ -163,6 +173,8 @@ public record Options(RailSide railSide, /** * Default Nordic look: left rail, teal accent, pale rail fill, * and profile fill read from {@code CvTheme.nordicClean()}. + * + * @return the default Nordic options */ public static Options defaults() { return new Options(RailSide.LEFT, null, null, null); @@ -170,6 +182,8 @@ public static Options defaults() { /** * Starts a mutable builder for ergonomic colour overrides. + * + * @return new builder */ public static Builder builder() { return new Builder(); @@ -193,26 +207,55 @@ public static final class Builder { private Builder() { } + /** + * Sets the side carrying the skills/education rail. + * + * @param value rail side + * @return this builder + */ public Builder railSide(RailSide value) { this.railSide = value; return this; } + /** + * Sets the teal accent for rules, links, and the underline. + * + * @param value accent colour + * @return this builder + */ public Builder accentColor(DocumentColor value) { this.accentColor = value; return this; } + /** + * Sets the fill behind the rail column. + * + * @param value rail fill colour + * @return this builder + */ public Builder railFillColor(DocumentColor value) { this.railFillColor = value; return this; } + /** + * Sets the profile band fill. + * + * @param value profile band fill colour + * @return this builder + */ public Builder profileFillColor(DocumentColor value) { this.profileFillColor = value; return this; } + /** + * Builds the configured options. + * + * @return a new {@link Options} with the configured values + */ public Options build() { return new Options(railSide, accentColor, railFillColor, profileFillColor); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/Panel.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/Panel.java index 959c57bd..a424b343 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/Panel.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/Panel.java @@ -123,6 +123,8 @@ private Panel() { /** * Builds the preset with its Panel theme. + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.panel()); @@ -130,6 +132,9 @@ public static DocumentTemplate create() { /** * Builds the preset with a caller-supplied theme. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/SidebarPortrait.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/SidebarPortrait.java index 3ae13e30..f5251545 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/SidebarPortrait.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/SidebarPortrait.java @@ -180,6 +180,8 @@ private SidebarPortrait() { * Builds the preset with its Sidebar Portrait theme and default * options (theme's banner fill for the sidebar, white for the * main column, mid-grey accent rule). + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.sidebarPortrait(), Options.defaults()); @@ -188,6 +190,9 @@ public static DocumentTemplate create() { /** * Builds the preset with a caller-supplied theme and default * options. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { return create(theme, Options.defaults()); @@ -197,6 +202,10 @@ public static DocumentTemplate create(CvTheme theme) { * Builds the preset with explicit colour options. Use this to * override the sidebar fill, main fill or accent colour without * forking the theme. + * + * @param theme active theme + * @param options sidebar colour options + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme, Options options) { @@ -220,14 +229,28 @@ public record Options(DocumentColor sidebarFillColor, DocumentColor mainFillColor, DocumentColor accentColor) { + /** + * Default options: every field unset, falling back to the V1 + * defaults. + * + * @return options that leave the committed look unchanged + */ public static Options defaults() { return new Options(null, null, null); } + /** + * Starts a mutable builder for the sidebar colour knobs. + * + * @return new builder + */ public static Builder builder() { return new Builder(); } + /** + * Builder for {@link Options}. + */ public static final class Builder { private DocumentColor sidebarFillColor; private DocumentColor mainFillColor; @@ -236,21 +259,44 @@ public static final class Builder { private Builder() { } + /** + * Sets the sidebar column fill. + * + * @param value sidebar fill colour + * @return this builder + */ public Builder sidebarFillColor(DocumentColor value) { this.sidebarFillColor = value; return this; } + /** + * Sets the main column fill. + * + * @param value main fill colour + * @return this builder + */ public Builder mainFillColor(DocumentColor value) { this.mainFillColor = value; return this; } + /** + * Sets the divider rule colour above each sidebar heading. + * + * @param value accent colour + * @return this builder + */ public Builder accentColor(DocumentColor value) { this.accentColor = value; return this; } + /** + * Builds the configured options. + * + * @return a new {@link Options} with the configured colours + */ public Options build() { return new Options(sidebarFillColor, mainFillColor, accentColor); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/TimelineMinimal.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/TimelineMinimal.java index 571a1121..4ca981ee 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/TimelineMinimal.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/presets/TimelineMinimal.java @@ -112,6 +112,8 @@ private TimelineMinimal() { /** * Builds the preset with its Timeline Minimal theme. + * + * @return ready-to-use template */ public static DocumentTemplate create() { return create(CvTheme.timelineMinimal()); @@ -119,6 +121,9 @@ public static DocumentTemplate create() { /** * Builds the preset with a caller-supplied theme. + * + * @param theme active theme + * @return ready-to-use template */ public static DocumentTemplate create(CvTheme theme) { Objects.requireNonNull(theme, "theme"); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvDecoration.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvDecoration.java index ebc40a18..212d479a 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvDecoration.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvDecoration.java @@ -34,6 +34,7 @@ public record CvDecoration(String bulletGlyph, String stackedIndent, String contactSeparator) { + /** Validates that no token is null. */ public CvDecoration { Objects.requireNonNull(bulletGlyph, "bulletGlyph"); Objects.requireNonNull(stackedIndent, "stackedIndent"); @@ -43,6 +44,8 @@ public record CvDecoration(String bulletGlyph, /** * The classic decoration: round bullet, two-space stacked indent, * pipe contact separator. Used by {@link CvTheme#boxedClassic()}. + * + * @return a {@code CvDecoration} for the classic look */ public static CvDecoration classic() { return new CvDecoration("• ", " ", " | "); @@ -51,6 +54,8 @@ public static CvDecoration classic() { /** * Blue Banner keeps classic bullets but uses the tighter contact * separator spacing from the legacy preset. + * + * @return a {@code CvDecoration} for the Blue Banner look */ public static CvDecoration blueBanner() { return new CvDecoration("• ", " ", " | "); @@ -60,6 +65,8 @@ public static CvDecoration blueBanner() { * Compact Mono uses slash-separated contact metadata in its dark * command-bar header. Row bullets keep the classic glyph for * callers that reuse shared row renderers with this theme. + * + * @return a {@code CvDecoration} for the Compact Mono look */ public static CvDecoration compactMono() { return new CvDecoration("• ", " ", " / "); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvPalette.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvPalette.java index 743155d3..a497e9ca 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvPalette.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvPalette.java @@ -24,6 +24,7 @@ public record CvPalette(DocumentColor ink, DocumentColor banner, DocumentColor mainFill) { + /** Validates that no colour token is null. */ public CvPalette { Objects.requireNonNull(ink, "ink"); Objects.requireNonNull(muted, "muted"); @@ -38,6 +39,12 @@ public record CvPalette(DocumentColor ink, * factories defined before the {@code mainFill} token landed keep * compiling and behaving identically (none of them rendered a * coloured main area). + * + * @param ink primary text colour — headlines, body, entry titles + * @param muted secondary text colour — italic subtitles (employer, + * institution) + * @param rule thin horizontal rules + the contact-line pipe glyph + * @param banner pale fill behind section title banners */ public CvPalette(DocumentColor ink, DocumentColor muted, @@ -49,6 +56,8 @@ public CvPalette(DocumentColor ink, /** * The classic dark-grey / pale-grey palette used by the original * Boxed Sections preset. + * + * @return a {@code CvPalette} for the classic flavour */ public static CvPalette classic() { return new CvPalette( @@ -69,6 +78,8 @@ public static CvPalette classic() { * we reuse the classic banner colour so themes can swap the body * style without leaving an obvious gap if a future preset reuses * this palette with a banner-style section header.

+ * + * @return a {@code CvPalette} for the Centered Headline flavour */ public static CvPalette centeredHeadline() { return new CvPalette( @@ -83,6 +94,8 @@ public static CvPalette centeredHeadline() { * v1 preset. The banner slot carries the soft cream fill used by * its profile band; the bronze accent is preset-local because no * other preset shares that fifth colour token today. + * + * @return a {@code CvPalette} for the Classic Serif flavour */ public static CvPalette classicSerif() { return new CvPalette( @@ -97,6 +110,8 @@ public static CvPalette classicSerif() { * metadata, pale teal rules, and the soft profile band fill. The * stronger teal accent and rail fill are preset-local fifth/sixth * colours because no other preset shares those tokens yet. + * + * @return a {@code CvPalette} for the Nordic Clean flavour */ public static CvPalette nordicClean() { return new CvPalette( @@ -110,6 +125,8 @@ public static CvPalette nordicClean() { * Compact Mono palette: near-black body ink, blue-grey metadata, * quiet card rules, and the pale rail fill used by the compact * left column. + * + * @return a {@code CvPalette} for the Compact Mono flavour */ public static CvPalette compactMono() { return new CvPalette( @@ -122,6 +139,8 @@ public static CvPalette compactMono() { /** * Blue Banner palette: compact dark ink, blue section fills, and * darker blue separator rules. + * + * @return a {@code CvPalette} for the Blue Banner flavour */ public static CvPalette blueBanner() { return new CvPalette( @@ -135,6 +154,8 @@ public static CvPalette blueBanner() { * Editorial Blue palette: deep blue-grey body text, muted * subtitles, vivid blue rules, and a neutral border token reused * by compact skill grids. + * + * @return a {@code CvPalette} for the Editorial Blue flavour */ public static CvPalette editorialBlue() { return new CvPalette( @@ -152,6 +173,8 @@ public static CvPalette editorialBlue() { * accent and rule colour are reused; main and sidebar tones share * the same {@code ink}/{@code muted} pair because the preset uses * a restrained grey palette throughout. + * + * @return a {@code CvPalette} for the Sidebar Portrait flavour */ public static CvPalette sidebarPortrait() { return new CvPalette( @@ -168,6 +191,8 @@ public static CvPalette sidebarPortrait() { * pale teal-grey sidebar background fill. The dark monogram ring * and muted-gold accent stay preset-local because no other v2 * preset shares them today. + * + * @return a {@code CvPalette} for the Monogram Sidebar flavour */ public static CvPalette monogramSidebar() { return new CvPalette( @@ -185,6 +210,8 @@ public static CvPalette monogramSidebar() { * navy header, brighter green accent, navy-rail variants and the * cyan-green contact link colour stay preset-local as they are the * fifth+ tokens — no other v2 preset shares them today. + * + * @return a {@code CvPalette} for the Engineering Resume flavour */ public static CvPalette engineeringResume() { return new CvPalette( @@ -200,6 +227,8 @@ public static CvPalette engineeringResume() { * softer grey for metadata + body bullets, pale rule for the * timeline axis and module underlines, and the dot token reused * for the three circles of the central timeline axis. + * + * @return a {@code CvPalette} for the Timeline Minimal flavour */ public static CvPalette timelineMinimal() { return new CvPalette( @@ -217,6 +246,8 @@ public static CvPalette timelineMinimal() { * navy (rgb(20,44,66)), teal accent (rgb(0,128,128)), and white * panel fill are preset-local because they are the fifth/sixth/ * seventh tokens — other v2 presets do not share them today. + * + * @return a {@code CvPalette} for the Panel flavour */ public static CvPalette panel() { return new CvPalette( @@ -235,6 +266,8 @@ public static CvPalette panel() { * rgb(24,35,51)) and bronze accent (rgb(172,112,55)) are * preset-local because they are the fifth and sixth tokens — * other v2 presets do not share them today. + * + * @return a {@code CvPalette} for the Executive flavour */ public static CvPalette executive() { return new CvPalette( @@ -253,6 +286,8 @@ public static CvPalette executive() { * the CV preset and its paired cover letter read * {@code palette.banner()} as the single accent source, so the * matched set never forks the colour. + * + * @return a {@code CvPalette} for the Mint Editorial flavour */ public static CvPalette mintEditorial() { return new CvPalette( diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvSpacing.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvSpacing.java index f9c38c3a..769eeaa6 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvSpacing.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvSpacing.java @@ -56,6 +56,7 @@ public record CvSpacing( double entryDateWeight, double entrySeparation) { + /** Validates that no inset token is null. */ public CvSpacing { Objects.requireNonNull(sectionBodyPadding, "sectionBodyPadding"); Objects.requireNonNull(headlinePadding, "headlinePadding"); @@ -70,6 +71,24 @@ public record CvSpacing( * compiling and rendering the same density as before, plus an * automatic improvement: a small gap between consecutive entries. * + * @param pageFlowSpacing gap between top-level page-flow rows + * @param sectionBodySpacing gap between paragraphs inside a + * section body + * @param sectionBodyPadding inset around section body content + * @param headlinePadding inset around the top headline + * @param contactPadding inset around the contact line + * @param bannerCornerRadius corner radius of the section-title + * banner panel + * @param bannerInnerPadding padding inside the banner panel + * @param bannerMargin margin around the banner panel + * @param accentRuleWidth stroke width of the thin horizontal + * rules under headline / contact + * @param paragraphMarginTop top margin applied to body paragraphs + * and rows so consecutive items breathe + * @param entryHeaderRowSpacing horizontal gap between an entry's + * title column and date column + * @param entryTitleWeight flex weight of the entry title column + * @param entryDateWeight flex weight of the entry date column * @deprecated since {@code entrySeparation} was introduced. * Supply it explicitly via the 14-arg canonical * constructor or via {@link #classic()} / @@ -98,6 +117,8 @@ public CvSpacing(double pageFlowSpacing, /** * The classic spacing used by the original Boxed Sections preset. + * + * @return a {@code CvSpacing} for the classic preset */ public static CvSpacing classic() { return new CvSpacing( @@ -124,6 +145,8 @@ public static CvSpacing classic() { * sections. Banner-panel fields are left at sensible defaults but * unused (the preset uses {@code flatSpacedCaps} section headers, * not banners). + * + * @return a {@code CvSpacing} for the Centered Headline preset */ public static CvSpacing centeredHeadline() { return new CvSpacing( @@ -147,6 +170,8 @@ public static CvSpacing centeredHeadline() { * Spacing for Classic Serif: a measured editorial flow with a * framed profile band, quiet cover skills module, and compact * detail modules. + * + * @return a {@code CvSpacing} for the Classic Serif preset */ public static CvSpacing classicSerif() { return new CvSpacing( @@ -169,6 +194,8 @@ public static CvSpacing classicSerif() { /** * Spacing for Nordic Clean: compact top header, soft profile band, * and a dense two-column body with a tinted sidebar rail. + * + * @return a {@code CvSpacing} for the Nordic Clean preset */ public static CvSpacing nordicClean() { return new CvSpacing( @@ -191,6 +218,8 @@ public static CvSpacing nordicClean() { /** * Spacing for Compact Mono: command-bar header, dense rail * modules, and same-width cards in the right column. + * + * @return a {@code CvSpacing} for the Compact Mono preset */ public static CvSpacing compactMono() { return new CvSpacing( @@ -216,6 +245,8 @@ public static CvSpacing compactMono() { * Banner-related fields (corner radius, inner padding, margin) * are left non-zero so a future preset that wants to draw an MP * banner can read them; the canonical MP preset ignores them. + * + * @return a {@code CvSpacing} for the Modern Professional preset */ public static CvSpacing modernProfessional() { return new CvSpacing( @@ -238,6 +269,8 @@ public static CvSpacing modernProfessional() { /** * Compact spacing for Blue Banner: tight body blocks, full-width * title banners, and no extra artificial gap between entries. + * + * @return a {@code CvSpacing} for the Blue Banner preset */ public static CvSpacing blueBanner() { return new CvSpacing( @@ -260,6 +293,8 @@ public static CvSpacing blueBanner() { /** * Compact spacing for Editorial Blue: section headers own their * rule/title rhythm, while bodies start close to the lower rule. + * + * @return a {@code CvSpacing} for the Editorial Blue preset */ public static CvSpacing editorialBlue() { return new CvSpacing( @@ -285,6 +320,8 @@ public static CvSpacing editorialBlue() { * RECOMMENDED_MARGIN=0 page bounds. Banner tokens are unused — * the preset draws its chrome inline (portrait photo, hero strip, * rules). + * + * @return a {@code CvSpacing} for the Sidebar Portrait preset */ public static CvSpacing sidebarPortrait() { return new CvSpacing( @@ -311,6 +348,8 @@ public static CvSpacing sidebarPortrait() { * page by {@code DocumentSession.pageBackgrounds(...)}, not by this * spacing; banner tokens are unused — the preset only draws the * monogram badge and sidebar heading rules inline. + * + * @return a {@code CvSpacing} for the Monogram Sidebar preset */ public static CvSpacing monogramSidebar() { return new CvSpacing( @@ -335,6 +374,8 @@ public static CvSpacing monogramSidebar() { * + 2-column body (navy skill rail / white evidence cards), with * a 2.5pt accent rule under the header and tight 1pt paragraph * top so the dense rail + card content reads as a single page. + * + * @return a {@code CvSpacing} for the Engineering Resume preset */ public static CvSpacing engineeringResume() { return new CvSpacing( @@ -359,6 +400,8 @@ public static CvSpacing engineeringResume() { * with a fixed-width axis between the sidebar and main column. * Body content is text-only (no cards / banners), so banner * tokens are unused but kept at neutral defaults. + * + * @return a {@code CvSpacing} for the Timeline Minimal preset */ public static CvSpacing timelineMinimal() { return new CvSpacing( @@ -383,6 +426,8 @@ public static CvSpacing timelineMinimal() { * Header / Profile / two-column row / Additional on one A4 page, * so paddings and inter-card gaps are tight by design. Corner * radius and accent rule width match the V1 ProductLeader tokens. + * + * @return a {@code CvSpacing} for the Panel preset */ public static CvSpacing panel() { return new CvSpacing( @@ -406,6 +451,8 @@ public static CvSpacing panel() { * Spacing for the Executive preset: generous executive feel with * an 8pt page-flow rhythm, compact module bodies, and a 1.1pt * full-width rule under the masthead. + * + * @return a {@code CvSpacing} for the Executive preset */ public static CvSpacing executive() { return new CvSpacing( @@ -432,6 +479,8 @@ public static CvSpacing executive() { * tight section bodies. The two-column sidebar/main split and its * column gap are page-composition concerns owned by the preset, not * spacing tokens. + * + * @return a {@code CvSpacing} for the Mint Editorial preset */ public static CvSpacing mintEditorial() { return new CvSpacing( diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvTheme.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvTheme.java index 7f866831..2229da82 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvTheme.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvTheme.java @@ -23,12 +23,14 @@ * @param palette colour tokens * @param typography font + size scale * @param spacing paddings / margins / weights + * @param decoration glyph / separator tokens */ public record CvTheme(CvPalette palette, CvTypography typography, CvSpacing spacing, CvDecoration decoration) { + /** Validates that no sub-record is null. */ public CvTheme { Objects.requireNonNull(palette, "palette"); Objects.requireNonNull(typography, "typography"); @@ -42,6 +44,9 @@ public record CvTheme(CvPalette palette, * Retained so callers built before the decoration token landed * keep compiling and behaving identically. * + * @param palette colour tokens + * @param typography font + size scale + * @param spacing paddings / margins / weights * @deprecated since the introduction of {@link CvDecoration} — * pass an explicit decoration so callers can choose * a different bullet glyph or contact separator @@ -59,6 +64,8 @@ public CvTheme(CvPalette palette, CvTypography typography, CvSpacing spacing) { * pale-grey section banners, round bullets, pipe contact * separators. Visual signature of the original * {@code cv-boxed-sections.pdf} reference output. + * + * @return a {@code CvTheme} for the "Boxed Sections" classic look */ public static CvTheme boxedClassic() { return new CvTheme( @@ -78,6 +85,8 @@ public static CvTheme boxedClassic() { *

When (or if) a second preset wants the same accent palette, * extract those colours into a new field on {@link CvPalette} and * point both presets at it.

+ * + * @return a {@code CvTheme} for the "Modern Professional" look */ public static CvTheme modernProfessional() { return new CvTheme( @@ -93,6 +102,8 @@ public static CvTheme modernProfessional() { * palette, thin full-width rules separating headline / contact / * each module. Pipe contact separator matches the classic * decoration. + * + * @return a {@code CvTheme} for the "Centered Headline" look */ public static CvTheme centeredHeadline() { return new CvTheme( @@ -106,6 +117,8 @@ public static CvTheme centeredHeadline() { * The "Classic Serif" look — PT Serif throughout, warm dark ink, * tan rules, cream profile band, and the roomy pipe separator * from the classic decoration. + * + * @return a {@code CvTheme} for the "Classic Serif" look */ public static CvTheme classicSerif() { return new CvTheme( @@ -119,6 +132,8 @@ public static CvTheme classicSerif() { * The "Nordic Clean" look — Barlow display typography, Lato body, * deep blue-green ink, pale teal profile band/rules, and compact * two-column spacing. + * + * @return a {@code CvTheme} for the "Nordic Clean" look */ public static CvTheme nordicClean() { return new CvTheme( @@ -132,6 +147,8 @@ public static CvTheme nordicClean() { * The "Compact Mono" look — dark command-bar header, IBM Plex * Mono labels, teal accents, pale left rail, and compact card * spacing. + * + * @return a {@code CvTheme} for the "Compact Mono" look */ public static CvTheme compactMono() { return new CvTheme( @@ -145,6 +162,8 @@ public static CvTheme compactMono() { * The "Blue Banner" look — PT Serif display name, Lato body, * compact spacing, blue full-width section banners, and tighter * pipe separators. + * + * @return a {@code CvTheme} for the "Blue Banner" look */ public static CvTheme blueBanner() { return new CvTheme( @@ -158,6 +177,8 @@ public static CvTheme blueBanner() { * The "Editorial Blue" look — compact Helvetica, vivid blue * section rules, centred editorial header, and dense body * spacing. + * + * @return a {@code CvTheme} for the "Editorial Blue" look */ public static CvTheme editorialBlue() { return new CvTheme( @@ -176,6 +197,8 @@ public static CvTheme editorialBlue() { * via a hero strip), professional profile, and experience * timeline. Visual signature ported from the v1 * {@code SidebarPortraitCvTemplateComposer}. + * + * @return a {@code CvTheme} for the "Sidebar Portrait" look */ public static CvTheme sidebarPortrait() { return new CvTheme( @@ -193,6 +216,8 @@ public static CvTheme sidebarPortrait() { * headline and main career narrative on the right. Visual * signature ported from the v1 * {@code MonogramSidebarCvTemplateComposer}. + * + * @return a {@code CvTheme} for the "Monogram Sidebar" look */ public static CvTheme monogramSidebar() { return new CvTheme( @@ -209,6 +234,8 @@ public static CvTheme monogramSidebar() { * for Leadership Experience + Technical Evidence on the right. * Visual signature ported from the v1 * {@code TechLeadCvTemplateComposer}. + * + * @return a {@code CvTheme} for the "Engineering Resume" look */ public static CvTheme engineeringResume() { return new CvTheme( @@ -225,6 +252,8 @@ public static CvTheme engineeringResume() { * with three circles separating the sidebar from the main column. * Visual signature ported from the v1 * {@code TimelineMinimalCvTemplateComposer}. + * + * @return a {@code CvTheme} for the "Timeline Minimal" look */ public static CvTheme timelineMinimal() { return new CvTheme( @@ -240,6 +269,8 @@ public static CvTheme timelineMinimal() { * masthead text, and teal section headings with a small accent * strip beneath each title. Visual signature ported from the v1 * {@code PanelCvTemplateComposer} (ProductLeader tokens). + * + * @return a {@code CvTheme} for the "Panel" look */ public static CvTheme panel() { return new CvTheme( @@ -255,6 +286,8 @@ public static CvTheme panel() { * links, and a thin full-width muted rule under the header. * Visual signature ported from the legacy * {@code ExecutiveSlateCvTemplate}. + * + * @return a {@code CvTheme} for the "Executive" look */ public static CvTheme executive() { return new CvTheme( @@ -273,6 +306,8 @@ public static CvTheme executive() { * skill bars, social) beside a main column (profile, experience, * awards, references). Paired 1:1 with the Mint Editorial cover * letter, which reuses this exact theme. + * + * @return a {@code CvTheme} for the "Mint Editorial" look */ public static CvTheme mintEditorial() { return new CvTheme( @@ -287,46 +322,104 @@ public static CvTheme mintEditorial() { // call site. This is the only "computed" code in the theme — every // value reads from the underlying records. + /** + * Composed text style for the top-of-document headline — headline + * font at the headline size in the primary ink colour. + * + * @return the headline text style + */ public DocumentTextStyle headlineStyle() { return style(typography.headlineFont(), typography.sizeHeadline(), DocumentTextDecoration.DEFAULT, palette.ink()); } + /** + * Composed text style for the bold spaced-caps section banner + * label — headline font at the banner size in the primary ink + * colour. + * + * @return the banner text style + */ public DocumentTextStyle bannerStyle() { return style(typography.headlineFont(), typography.sizeBanner(), DocumentTextDecoration.BOLD, palette.ink()); } + /** + * Composed text style for the contact line — body font at the + * contact size in the primary ink colour. + * + * @return the contact text style + */ public DocumentTextStyle contactStyle() { return style(typography.bodyFont(), typography.sizeContact(), DocumentTextDecoration.DEFAULT, palette.ink()); } + /** + * Composed text style for the separator glyph between contact + * items — body font at the contact size in the quieter rule + * colour. + * + * @return the contact-separator text style + */ public DocumentTextStyle contactSeparatorStyle() { return style(typography.bodyFont(), typography.sizeContact(), DocumentTextDecoration.DEFAULT, palette.rule()); } + /** + * Composed text style for body prose — body font at the body size + * in the primary ink colour. + * + * @return the body text style + */ public DocumentTextStyle bodyStyle() { return style(typography.bodyFont(), typography.sizeBody(), DocumentTextDecoration.DEFAULT, palette.ink()); } + /** + * Composed text style for emphasised body text — body font at the + * body size, bold, in the primary ink colour. + * + * @return the bold body text style + */ public DocumentTextStyle bodyBoldStyle() { return style(typography.bodyFont(), typography.sizeBody(), DocumentTextDecoration.BOLD, palette.ink()); } + /** + * Composed text style for an entry title (job title, degree) — + * body font at the entry-title size, bold, in the primary ink + * colour. + * + * @return the entry-title text style + */ public DocumentTextStyle entryTitleStyle() { return style(typography.bodyFont(), typography.sizeEntryTitle(), DocumentTextDecoration.BOLD, palette.ink()); } + /** + * Composed text style for the right-aligned entry date column — + * body font at the entry-date size in the primary ink colour. + * + * @return the entry-date text style + */ public DocumentTextStyle entryDateStyle() { return style(typography.bodyFont(), typography.sizeEntryDate(), DocumentTextDecoration.DEFAULT, palette.ink()); } + /** + * Composed text style for an italic entry subtitle (employer, + * institution) — body font at the entry-subtitle size, italic, in + * the muted secondary colour. + * + * @return the entry-subtitle text style + */ public DocumentTextStyle entrySubtitleStyle() { return style(typography.bodyFont(), typography.sizeEntrySubtitle(), DocumentTextDecoration.ITALIC, palette.muted()); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvTypography.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvTypography.java index 8d053584..6cdaf184 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvTypography.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/theme/CvTypography.java @@ -40,6 +40,7 @@ public record CvTypography( double sizeBody, double bodyLineSpacing) { + /** Validates that the font tokens are not null. */ public CvTypography { Objects.requireNonNull(headlineFont, "headlineFont"); Objects.requireNonNull(bodyFont, "bodyFont"); @@ -48,6 +49,8 @@ public record CvTypography( /** * The classic PT-Serif scale used by the original Boxed Sections * preset. + * + * @return a {@code CvTypography} scale for the classic preset */ public static CvTypography classic() { return new CvTypography( @@ -65,6 +68,8 @@ public static CvTypography classic() { /** * Helvetica scale for the Modern Professional preset — larger * display name, larger section titles, comfortable body size. + * + * @return a {@code CvTypography} scale for the Modern Professional preset */ public static CvTypography modernProfessional() { return new CvTypography( @@ -89,6 +94,8 @@ public static CvTypography modernProfessional() { * {@link com.demcha.compose.document.templates.cv.v2.widgets.SectionHeader#flatSpacedCaps} * variant — small bold spaced-caps title in the soft palette * tone.

+ * + * @return a {@code CvTypography} scale for the Centered Headline preset */ public static CvTypography centeredHeadline() { return new CvTypography( @@ -108,6 +115,8 @@ public static CvTypography centeredHeadline() { * editorial masthead, quiet metadata, and compact detail entries. * Preset-local body variants still override this when the visual * needs a distinct summary size. + * + * @return a {@code CvTypography} scale for the Classic Serif preset */ public static CvTypography classicSerif() { return new CvTypography( @@ -126,6 +135,8 @@ public static CvTypography classicSerif() { * Barlow headline + Lato body scale for the {@code NordicClean} * preset. Compact sizes keep the two-column rail/body layout * single-page friendly while preserving the crisp editorial feel. + * + * @return a {@code CvTypography} scale for the Nordic Clean preset */ public static CvTypography nordicClean() { return new CvTypography( @@ -144,6 +155,8 @@ public static CvTypography nordicClean() { * IBM Plex Mono headline + Lato body scale for the Compact Mono * preset. The section-title slot also uses the mono headline font * so tick labels keep the terminal/card visual signature. + * + * @return a {@code CvTypography} scale for the Compact Mono preset */ public static CvTypography compactMono() { return new CvTypography( @@ -161,6 +174,8 @@ public static CvTypography compactMono() { /** * Compact PT-Serif headline + Lato body scale used by the Blue * Banner preset. + * + * @return a {@code CvTypography} scale for the Blue Banner preset */ public static CvTypography blueBanner() { return new CvTypography( @@ -177,6 +192,8 @@ public static CvTypography blueBanner() { /** * Compact Helvetica scale for the Editorial Blue preset. + * + * @return a {@code CvTypography} scale for the Editorial Blue preset */ public static CvTypography editorialBlue() { return new CvTypography( @@ -197,6 +214,8 @@ public static CvTypography editorialBlue() { * 12pt main section title, 10pt body, and 8-9pt sidebar metadata. * The sample data is information-dense, so the body sizes are * compact and the line spacing trends to 1.35 for readability. + * + * @return a {@code CvTypography} scale for the Sidebar Portrait preset */ public static CvTypography sidebarPortrait() { return new CvTypography( @@ -218,6 +237,8 @@ public static CvTypography sidebarPortrait() { * body sizes across the pale-teal sidebar and the right column. * The PT-Serif monogram font is preset-local because no other v2 * preset uses it for a circle-ring badge. + * + * @return a {@code CvTypography} scale for the Monogram Sidebar preset */ public static CvTypography monogramSidebar() { return new CvTypography( @@ -237,6 +258,8 @@ public static CvTypography monogramSidebar() { * {@code TechLeadCvTemplateComposer}: 24.5pt UPPERCASE masthead, * 7.8pt main section headings, 7.25pt body, and a 1.08 line * spacing tuned for dense engineering-resume cards. + * + * @return a {@code CvTypography} scale for the Engineering Resume preset */ public static CvTypography engineeringResume() { return new CvTypography( @@ -257,6 +280,8 @@ public static CvTypography engineeringResume() { * masthead, 12.5pt sidebar module titles, 13.5pt main module * titles, 7.5-7.9pt body. Compact sizes squeeze the 3-column * sidebar / axis / main layout onto one page. + * + * @return a {@code CvTypography} scale for the Timeline Minimal preset */ public static CvTypography timelineMinimal() { return new CvTypography( @@ -277,6 +302,8 @@ public static CvTypography timelineMinimal() { * uppercase name in the tinted header card, a 10.4pt section-title * slot for the teal module headings, and a 9.4pt body with 1.2 * line spacing tuned for the dense card layout. + * + * @return a {@code CvTypography} scale for the Panel preset */ public static CvTypography panel() { return new CvTypography( @@ -297,6 +324,8 @@ public static CvTypography panel() { * 10.8pt section-title slot driving the bronze module headings, * and a 9.5pt body with 1.25 line-spacing tuned for an executive * single-column resume density. + * + * @return a {@code CvTypography} scale for the Executive preset */ public static CvTypography executive() { return new CvTypography( @@ -316,6 +345,8 @@ public static CvTypography executive() { * 26pt spaced-caps centered name, an 11pt spaced-caps accent section * heading, and compact 7.4-8pt metadata/body tuned for the dense * two-column editorial layout. + * + * @return a {@code CvTypography} scale for the Mint Editorial preset */ public static CvTypography mintEditorial() { return new CvTypography( diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/ContactLine.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/ContactLine.java index 6a8c5aee..d122844c 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/ContactLine.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/ContactLine.java @@ -47,6 +47,10 @@ private ContactLine() { * Centred pipe-separated contact row. Order: phone → email → * address → links. Visual signature of {@code BoxedSections}, * {@code MinimalUnderlined}. + * + * @param host the section builder the contact row is appended to + * @param identity the CV identity supplying contact fields and links + * @param theme the active theme supplying palette, typography, and spacing */ public static void centered(SectionBuilder host, CvIdentity identity, CvTheme theme) { render(host, identity, theme, TextAlign.CENTER, Order.PHONE_FIRST); @@ -59,6 +63,9 @@ public static void centered(SectionBuilder host, CvIdentity identity, CvTheme th * editorial presets tint / underline the links without forking the * contact assembly logic. * + * @param host the section builder the contact row is appended to + * @param identity the CV identity supplying contact fields and links + * @param theme the active theme supplying palette, typography, and spacing * @param bodyStyleOverride style for phone and address; * {@code null} → * {@code theme.contactStyle()} @@ -82,6 +89,10 @@ public static void centered(SectionBuilder host, CvIdentity identity, * Right-aligned pipe-separated contact row. Order: address → * phone → email → links — address-first reads as the location * label authors usually put first in this style. + * + * @param host the section builder the contact row is appended to + * @param identity the CV identity supplying contact fields and links + * @param theme the active theme supplying palette, typography, and spacing */ public static void rightAligned(SectionBuilder host, CvIdentity identity, CvTheme theme) { render(host, identity, theme, TextAlign.RIGHT, Order.ADDRESS_FIRST); @@ -91,6 +102,10 @@ public static void rightAligned(SectionBuilder host, CvIdentity identity, CvThem * Left-aligned contact row. Order: address -> phone -> email -> * links. Useful for command-bar headers where the name and * contact metadata both anchor to the left edge. + * + * @param host the section builder the contact row is appended to + * @param identity the CV identity supplying contact fields and links + * @param theme the active theme supplying palette, typography, and spacing */ public static void leftAligned(SectionBuilder host, CvIdentity identity, CvTheme theme) { @@ -101,6 +116,9 @@ public static void leftAligned(SectionBuilder host, CvIdentity identity, * Left-aligned contact row with explicit text-style overrides for * non-link text, clickable links, and separators. * + * @param host the section builder the contact row is appended to + * @param identity the CV identity supplying contact fields and links + * @param theme the active theme supplying palette, typography, and spacing * @param bodyStyleOverride style for address and phone; * {@code null} -> * {@code theme.contactStyle()} @@ -137,6 +155,9 @@ public static void leftAligned(SectionBuilder host, CvIdentity identity, * hyperlinks (mailto: for the email, the link's URL for each * label) — not just styled text.

* + * @param host the section builder the contact rows are appended to + * @param identity the CV identity supplying contact fields and links + * @param theme the active theme supplying palette, typography, and spacing * @param bodyStyleOverride style for the non-link items * (address, phone); {@code null} → * {@code theme.contactStyle()} @@ -191,6 +212,10 @@ public static void twoRowRightAligned(SectionBuilder host, CvIdentity identity, * Right-aligned contact stack, one item per line. Order: * address → phone → email → links. This is useful for two-column * headers where a pipe-separated row would become too wide. + * + * @param host the section builder the contact stack is appended to + * @param identity the CV identity supplying contact fields and links + * @param theme the active theme supplying palette, typography, and spacing */ public static void rightAlignedStacked(SectionBuilder host, CvIdentity identity, @@ -202,6 +227,9 @@ public static void rightAlignedStacked(SectionBuilder host, * Right-aligned contact stack with explicit text-style overrides * for non-link text and clickable links. * + * @param host the section builder the contact stack is appended to + * @param identity the CV identity supplying contact fields and links + * @param theme the active theme supplying palette, typography, and spacing * @param bodyStyleOverride style for address / phone; {@code null} * → {@code theme.contactStyle()} * @param linkStyleOverride style for email + links; {@code null} @@ -239,6 +267,12 @@ public static void rightAlignedStacked(SectionBuilder host, /** * Lower-level entry. Pick the alignment and the field order * explicitly. + * + * @param host the section builder the contact row is appended to + * @param identity the CV identity supplying contact fields and links + * @param theme the active theme supplying palette, typography, and spacing + * @param alignment horizontal text alignment for the row + * @param order the field order in the rendered line */ public static void render(SectionBuilder host, CvIdentity identity, CvTheme theme, TextAlign alignment, Order order) { diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/FlowSectionHeader.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/FlowSectionHeader.java index 4216e2f1..4507d96f 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/FlowSectionHeader.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/FlowSectionHeader.java @@ -25,6 +25,15 @@ private FlowSectionHeader() { /** * Renders a filled banner title with a rule above and below. * Visual signature of the Blue Banner preset. + * + * @param flow the page-flow builder the rules and banner section are added to + * @param name base node name used for the section and its surrounding rules + * @param title the section title text + * @param ruleWidth width in points of the rules above and below the banner + * @param theme the active theme supplying palette, typography, and spacing + * @param titleStyle text style for the banner title + * @param topRuleMargin outer margin of the rule above the banner + * @param bottomRuleMargin outer margin of the rule below the banner */ public static void banner(PageFlowBuilder flow, String name, @@ -40,6 +49,16 @@ public static void banner(PageFlowBuilder flow, /** * Renders a filled banner title with caller-controlled rule colour. + * + * @param flow the page-flow builder the rules and banner section are added to + * @param name base node name used for the section and its surrounding rules + * @param title the section title text + * @param ruleWidth width in points of the rules above and below the banner + * @param theme the active theme supplying palette, typography, and spacing + * @param titleStyle text style for the banner title + * @param ruleColor colour of the rules above and below the banner + * @param topRuleMargin outer margin of the rule above the banner + * @param bottomRuleMargin outer margin of the rule below the banner */ public static void banner(PageFlowBuilder flow, String name, @@ -61,6 +80,17 @@ public static void banner(PageFlowBuilder flow, /** * Renders a plain left-aligned title between horizontal rules. * Visual signature of the Editorial Blue preset. + * + * @param flow the page-flow builder the rules and title section are added to + * @param name base node name used for the section and its surrounding rules + * @param title the section title text + * @param ruleWidth width in points of the surrounding rules + * @param theme the active theme supplying palette, typography, and spacing + * @param titleStyle text style for the title + * @param topRuleMargin outer margin of the rule above the title + * @param titlePadding inner padding of the title section + * @param bottomRuleMargin outer margin of the rule below the title + * @param withTopRule whether to render the rule above the title */ public static void label(PageFlowBuilder flow, String name, @@ -80,6 +110,18 @@ public static void label(PageFlowBuilder flow, /** * Renders a plain left-aligned title with caller-controlled rule * colour. + * + * @param flow the page-flow builder the rules and title section are added to + * @param name base node name used for the section and its surrounding rules + * @param title the section title text + * @param ruleWidth width in points of the surrounding rules + * @param theme the active theme supplying palette, typography, and spacing + * @param titleStyle text style for the title + * @param ruleColor colour of the surrounding rules + * @param topRuleMargin outer margin of the rule above the title + * @param titlePadding inner padding of the title section + * @param bottomRuleMargin outer margin of the rule below the title + * @param withTopRule whether to render the rule above the title */ public static void label(PageFlowBuilder flow, String name, diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/Headline.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/Headline.java index ae770846..6f5eadb7 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/Headline.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/Headline.java @@ -50,6 +50,10 @@ private Headline() { /** * Centred letter-spaced uppercase headline. Visual signature of * {@code BoxedSections} and {@code MinimalUnderlined}. + * + * @param host host section the headline is appended to + * @param name name to render + * @param theme the active theme supplying palette, typography, and spacing */ public static void spacedCentered(SectionBuilder host, CvName name, CvTheme theme) { render(host, name, theme, TextAlign.CENTER, true); @@ -59,6 +63,10 @@ public static void spacedCentered(SectionBuilder host, CvName name, CvTheme them * Centred uppercase headline without letter spacing. Visual * signature of compact editorial presets that want a strong * masthead but not the wider classic spaced-caps treatment. + * + * @param host host section the headline is appended to + * @param name name to render + * @param theme the active theme supplying palette, typography, and spacing */ public static void uppercaseCentered(SectionBuilder host, CvName name, CvTheme theme) { @@ -69,6 +77,9 @@ public static void uppercaseCentered(SectionBuilder host, CvName name, * Centred uppercase headline without letter spacing and with an * explicit style override. * + * @param host host section the headline is appended to + * @param name name to render + * @param theme the active theme supplying palette, typography, and spacing * @param styleOverride explicit style; pass {@code null} to fall * back to {@code theme.headlineStyle()} */ @@ -83,6 +94,10 @@ public static void uppercaseCentered(SectionBuilder host, CvName name, * Left-aligned uppercase headline without letter spacing. Visual * signature of clean two-column presets where the name sits in the * top-left identity block rather than centred on the page. + * + * @param host host section the headline is appended to + * @param name name to render + * @param theme the active theme supplying palette, typography, and spacing */ public static void uppercaseLeftAligned(SectionBuilder host, CvName name, CvTheme theme) { @@ -93,6 +108,9 @@ public static void uppercaseLeftAligned(SectionBuilder host, CvName name, * Left-aligned uppercase headline without letter spacing and with * an explicit style override. * + * @param host host section the headline is appended to + * @param name name to render + * @param theme the active theme supplying palette, typography, and spacing * @param styleOverride explicit style; pass {@code null} to fall * back to {@code theme.headlineStyle()} */ @@ -108,6 +126,10 @@ public static void uppercaseLeftAligned(SectionBuilder host, CvName name, * {@link CvTheme#headlineStyle() headline style}. Visual * signature of corporate / modern presets that don't need a * custom display colour. + * + * @param host host section the headline is appended to + * @param name name to render + * @param theme the active theme supplying palette, typography, and spacing */ public static void rightAligned(SectionBuilder host, CvName name, CvTheme theme) { rightAligned(host, name, theme, null); @@ -119,6 +141,9 @@ public static void rightAligned(SectionBuilder host, CvName name, CvTheme theme) * / colour it wants. Used by {@code ModernProfessional} to apply * its preset-specific slate-blue display colour. * + * @param host host section the headline is appended to + * @param name name to render + * @param theme the active theme supplying palette, typography, and spacing * @param styleOverride text style for the headline; pass {@code null} * to fall back to {@code theme.headlineStyle()} */ @@ -150,6 +175,12 @@ public static void render(SectionBuilder host, CvName name, CvTheme theme, * the 5-arg {@link #render(SectionBuilder, CvName, CvTheme, TextAlign, boolean)} * but lets the caller supply a custom {@link DocumentTextStyle}. * + * @param host host section + * @param name name to render + * @param theme active theme + * @param alignment paragraph alignment + * @param spacedCaps if true, transforms to letter-spaced + * uppercase; if false, renders verbatim * @param styleOverride explicit style; pass {@code null} to fall * back to {@code theme.headlineStyle()} */ diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/Masthead.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/Masthead.java index 765c0803..3f8d1bed 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/Masthead.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/Masthead.java @@ -21,6 +21,16 @@ public final class Masthead { private Masthead() { } + /** + * Renders the centred masthead: name, optional job title, compact + * contact metadata, and a separate link row. + * + * @param host the section builder the masthead is appended to + * @param identity the CV identity supplying name, contact, and links + * @param theme the active theme supplying palette, typography, and spacing + * @param style styling knobs for the masthead; {@code null} uses + * {@link Style#defaults(CvTheme)} + */ public static void centered(SectionBuilder host, CvIdentity identity, CvTheme theme, @@ -126,6 +136,14 @@ private static String join(String separator, String... values) { /** * Styling knobs for the centred masthead. + * + * @param nameStyle text style for the name headline + * @param titleStyle text style for the optional job-title line + * @param metaStyle text style for the compact contact metadata line + * @param linkStyle text style for clickable links in the link row + * @param separatorStyle text style for the separator glyph between links + * @param metaJoiner string joining contact metadata values; defaults to {@code " - "} + * @param lineMargin outer margin applied to each masthead line */ public record Style(DocumentTextStyle nameStyle, DocumentTextStyle titleStyle, @@ -135,6 +153,7 @@ public record Style(DocumentTextStyle nameStyle, String metaJoiner, DocumentInsets lineMargin) { + /** Applies defaults for {@code metaJoiner} and {@code lineMargin}. */ public Style { metaJoiner = metaJoiner == null ? " - " : metaJoiner; lineMargin = lineMargin == null @@ -142,6 +161,13 @@ public record Style(DocumentTextStyle nameStyle, : lineMargin; } + /** + * Style derived from the theme's headline, body, contact, and + * separator styles. + * + * @param theme the active theme supplying the default styles + * @return a {@code Style} populated from the theme defaults + */ public static Style defaults(CvTheme theme) { return builder() .nameStyle(theme.headlineStyle()) @@ -152,10 +178,18 @@ public static Style defaults(CvTheme theme) { .build(); } + /** + * Creates a new {@link Builder} for the masthead style. + * + * @return a new empty {@code Builder} + */ public static Builder builder() { return new Builder(); } + /** + * Mutable builder for {@link Style}. + */ public static final class Builder { private DocumentTextStyle nameStyle; private DocumentTextStyle titleStyle; @@ -168,41 +202,88 @@ public static final class Builder { private Builder() { } + /** + * Sets the name headline style. + * + * @param value text style for the name headline + * @return this builder for chaining + */ public Builder nameStyle(DocumentTextStyle value) { this.nameStyle = value; return this; } + /** + * Sets the optional job-title line style. + * + * @param value text style for the job-title line + * @return this builder for chaining + */ public Builder titleStyle(DocumentTextStyle value) { this.titleStyle = value; return this; } + /** + * Sets the contact metadata line style. + * + * @param value text style for the contact metadata line + * @return this builder for chaining + */ public Builder metaStyle(DocumentTextStyle value) { this.metaStyle = value; return this; } + /** + * Sets the clickable-link style for the link row. + * + * @param value text style for clickable links + * @return this builder for chaining + */ public Builder linkStyle(DocumentTextStyle value) { this.linkStyle = value; return this; } + /** + * Sets the separator-glyph style between links. + * + * @param value text style for the separator glyph + * @return this builder for chaining + */ public Builder separatorStyle(DocumentTextStyle value) { this.separatorStyle = value; return this; } + /** + * Sets the string joining contact metadata values. + * + * @param value the metadata joiner string + * @return this builder for chaining + */ public Builder metaJoiner(String value) { this.metaJoiner = value; return this; } + /** + * Sets the outer margin applied to each masthead line. + * + * @param value outer margin for each line + * @return this builder for chaining + */ public Builder lineMargin(DocumentInsets value) { this.lineMargin = value; return this; } + /** + * Builds the {@link Style} from the configured values. + * + * @return a new {@code Style} + */ public Style build() { return new Style(nameStyle, titleStyle, metaStyle, linkStyle, separatorStyle, metaJoiner, lineMargin); diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/ProfileBand.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/ProfileBand.java index 54537e45..ed8dc211 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/ProfileBand.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/ProfileBand.java @@ -19,6 +19,17 @@ public final class ProfileBand { private ProfileBand() { } + /** + * Renders the profile band as a new named section in the page flow. + * Does nothing when {@code body} is {@code null} or blank. + * + * @param flow the page-flow builder the section is added to + * @param name node name used in snapshots and layout graph paths + * @param title the optional band title; skipped when null or blank + * @param body the rich-text body in inline-markdown form + * @param style styling knobs for the band; {@code null} uses + * {@link Style#defaults()} + */ public static void render(PageFlowBuilder flow, String name, String title, @@ -30,6 +41,16 @@ public static void render(PageFlowBuilder flow, flow.addSection(name, host -> render(host, title, body, style)); } + /** + * Renders the profile band into an existing section. Does nothing + * when {@code body} is {@code null} or blank. + * + * @param host the section builder the band is rendered into + * @param title the optional band title; skipped when null or blank + * @param body the rich-text body in inline-markdown form + * @param style styling knobs for the band; {@code null} uses + * {@link Style#defaults()} + */ public static void render(SectionBuilder host, String title, String body, @@ -79,6 +100,26 @@ public static void render(SectionBuilder host, bodyStyle))); } + /** + * Styling knobs for the profile band. + * + * @param spacing vertical spacing between children + * @param padding inner padding + * @param fillColor optional background fill + * @param cornerRadius optional render-only corner radius + * @param accentLeftColor optional left accent-bar colour + * @param accentLeftWidth width in points of the left accent bar + * @param accentTopColor optional top accent-bar colour + * @param accentTopWidth width in points of the top accent bar + * @param accentBottomColor optional bottom accent-bar colour + * @param accentBottomWidth width in points of the bottom accent bar + * @param titleStyle text style for the title; null suppresses the title + * @param titleAlign horizontal alignment of the title + * @param transformTitle whether the title is transformed to uppercase + * @param bodyStyle base text style for the body + * @param bodyAlign horizontal alignment of the body + * @param bodyLineSpacing extra space between wrapped body lines + */ public record Style(double spacing, DocumentInsets padding, DocumentColor fillColor, @@ -96,20 +137,34 @@ public record Style(double spacing, TextAlign bodyAlign, double bodyLineSpacing) { + /** Applies defaults for {@code padding}, {@code titleAlign}, and {@code bodyAlign}. */ public Style { padding = padding == null ? DocumentInsets.zero() : padding; titleAlign = titleAlign == null ? TextAlign.LEFT : titleAlign; bodyAlign = bodyAlign == null ? TextAlign.LEFT : bodyAlign; } + /** + * Style with all defaults applied. + * + * @return a {@code Style} built from default values + */ public static Style defaults() { return builder().build(); } + /** + * Creates a new {@link Builder} for the band style. + * + * @return a new empty {@code Builder} + */ public static Builder builder() { return new Builder(); } + /** + * Mutable builder for {@link Style}. + */ public static final class Builder { private double spacing; private DocumentInsets padding = DocumentInsets.zero(); @@ -131,74 +186,160 @@ public static final class Builder { private Builder() { } + /** + * Sets the vertical spacing between children. + * + * @param value vertical spacing between children + * @return this builder for chaining + */ public Builder spacing(double value) { this.spacing = value; return this; } + /** + * Sets the inner padding. + * + * @param value inner padding + * @return this builder for chaining + */ public Builder padding(DocumentInsets value) { this.padding = value; return this; } + /** + * Sets the optional background fill. + * + * @param value optional background fill + * @return this builder for chaining + */ public Builder fillColor(DocumentColor value) { this.fillColor = value; return this; } + /** + * Sets the optional render-only corner radius. + * + * @param value optional render-only corner radius + * @return this builder for chaining + */ public Builder cornerRadius(DocumentCornerRadius value) { this.cornerRadius = value; return this; } + /** + * Sets the left accent bar. + * + * @param color the left accent-bar colour + * @param width width in points of the left accent bar + * @return this builder for chaining + */ public Builder accentLeft(DocumentColor color, double width) { this.accentLeftColor = color; this.accentLeftWidth = width; return this; } + /** + * Sets the top accent bar. + * + * @param color the top accent-bar colour + * @param width width in points of the top accent bar + * @return this builder for chaining + */ public Builder accentTop(DocumentColor color, double width) { this.accentTopColor = color; this.accentTopWidth = width; return this; } + /** + * Sets the bottom accent bar. + * + * @param color the bottom accent-bar colour + * @param width width in points of the bottom accent bar + * @return this builder for chaining + */ public Builder accentBottom(DocumentColor color, double width) { this.accentBottomColor = color; this.accentBottomWidth = width; return this; } + /** + * Sets the title text style. + * + * @param value text style for the title; null suppresses the title + * @return this builder for chaining + */ public Builder titleStyle(DocumentTextStyle value) { this.titleStyle = value; return this; } + /** + * Sets the horizontal alignment of the title. + * + * @param value horizontal alignment of the title + * @return this builder for chaining + */ public Builder titleAlign(TextAlign value) { this.titleAlign = value; return this; } + /** + * Sets whether the title is transformed to uppercase. + * + * @param value {@code true} to uppercase the title + * @return this builder for chaining + */ public Builder transformTitle(boolean value) { this.transformTitle = value; return this; } + /** + * Sets the base text style for the body. + * + * @param value base text style for the body + * @return this builder for chaining + */ public Builder bodyStyle(DocumentTextStyle value) { this.bodyStyle = value; return this; } + /** + * Sets the horizontal alignment of the body. + * + * @param value horizontal alignment of the body + * @return this builder for chaining + */ public Builder bodyAlign(TextAlign value) { this.bodyAlign = value; return this; } + /** + * Sets the extra space between wrapped body lines. + * + * @param value extra space between wrapped body lines + * @return this builder for chaining + */ public Builder bodyLineSpacing(double value) { this.bodyLineSpacing = value; return this; } + /** + * Builds the {@link Style} from the configured values. + * + * @return a new {@code Style} + */ public Style build() { return new Style(spacing, padding, fillColor, cornerRadius, accentLeftColor, accentLeftWidth, diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/SectionHeader.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/SectionHeader.java index 839dc7a0..54e5a95c 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/SectionHeader.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/SectionHeader.java @@ -64,6 +64,10 @@ private SectionHeader() { /** * Pale-grey banner panel with centred spaced-caps title. Visual * signature of {@code BoxedSections}. + * + * @param host the section builder the header is appended to + * @param title the section title text + * @param theme the active theme supplying palette, typography, and spacing */ public static void banner(SectionBuilder host, String title, CvTheme theme) { host.softPanel(theme.palette().banner(), @@ -83,6 +87,10 @@ public static void banner(SectionBuilder host, String title, CvTheme theme) { * in the main page flow (for example {@code BlueBanner}), not a * soft inset panel. Any rules above or below the band are * page-flow ornaments and should be composed by the preset. + * + * @param host the section builder the header is appended to + * @param title the section title text + * @param theme the active theme supplying palette, typography, and spacing */ public static void fullWidthBanner(SectionBuilder host, String title, CvTheme theme) { fullWidthBanner(host, title, theme, null); @@ -91,6 +99,9 @@ public static void fullWidthBanner(SectionBuilder host, String title, CvTheme th /** * Full-width filled banner with an explicit title style override. * + * @param host the section builder the header is appended to + * @param title the section title text + * @param theme the active theme supplying palette, typography, and spacing * @param titleStyleOverride text style for the banner label; pass * {@code null} to use * {@link CvTheme#bannerStyle()} @@ -115,6 +126,10 @@ public static void fullWidthBanner(SectionBuilder host, String title, /** * Small left-aligned spaced-caps title with a thin accent rule * beneath. Visual signature of {@code MinimalUnderlined}. + * + * @param host the section builder the header is appended to + * @param title the section title text + * @param theme the active theme supplying palette, typography, and spacing */ public static void underlined(SectionBuilder host, String title, CvTheme theme) { DocumentTextStyle titleStyle = theme.entryTitleStyle(); @@ -133,8 +148,11 @@ public static void underlined(SectionBuilder host, String title, CvTheme theme) * no rule, no transform. Visual signature of * {@code ModernProfessional}. * + * @param host the section builder the header is appended to + * @param title the section title text * @param color the title colour — typically the preset's * accent colour + * @param theme the active theme supplying palette, typography, and spacing */ public static void flat(SectionBuilder host, String title, DocumentColor color, CvTheme theme) { @@ -215,6 +233,12 @@ public static void tickLabel(SectionBuilder host, String title, * Short accent tick above a compact uppercase label with an * explicit label style override. * + * @param host host section + * @param title label text, transformed to uppercase + * @param theme active theme; supplies the default mono label + * font and size + * @param color accent/tick and label colour + * @param tickWidth width of the short rule above the label * @param titleStyle explicit style override; pass {@code null} to * derive a bold style from the theme headline * font and banner size @@ -249,6 +273,13 @@ public static void tickLabel(SectionBuilder host, String title, * Uppercase label followed by a short rule. Used by side-rail * presets where a section title is a compact block heading rather * than a full-width page-flow banner. + * + * @param host the section builder the header is appended to + * @param title the section title text, transformed to uppercase + * @param theme the active theme supplying palette, typography, and spacing + * @param titleStyle text style for the label + * @param ruleColor colour of the rule beneath the label + * @param ruleWidth width in points of the rule beneath the label */ public static void upperRule(SectionBuilder host, String title, CvTheme theme, DocumentTextStyle titleStyle, @@ -270,6 +301,15 @@ public static void upperRule(SectionBuilder host, String title, * Left-aligned spaced-caps label followed by a short rule. Used by * classic/editorial CV modules that need a quiet title plus a * small accent underline. + * + * @param host the section builder the header is appended to + * @param title the section title text, transformed to spaced caps + * @param theme the active theme supplying palette, typography, and spacing + * @param titleStyle text style for the label; pass {@code null} for the theme-derived default + * @param ruleColor colour of the rule beneath the label + * @param ruleWidth width in points of the rule beneath the label + * @param ruleThickness thickness in points of the rule + * @param ruleMargin outer margin of the rule */ public static void spacedCapsRule(SectionBuilder host, String title, CvTheme theme, DocumentTextStyle titleStyle, diff --git a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/SectionModule.java b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/SectionModule.java index 1f0b550a..30e6721f 100644 --- a/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/SectionModule.java +++ b/src/main/java/com/demcha/compose/document/templates/cv/v2/widgets/SectionModule.java @@ -21,6 +21,15 @@ private SectionModule() { /** * Module headed by {@link SectionHeader#tickLabel}; useful for * compact card/terminal layouts. + * + * @param parent the section builder the module is appended to + * @param name node name used in snapshots and layout graph paths + * @param title the section title text + * @param theme the active theme supplying palette, typography, and spacing + * @param color accent/tick and label colour + * @param tickWidth width of the short tick above the label + * @param titleStyle text style for the label + * @param body callback drawing the section body */ public static void tick(SectionBuilder parent, String name, @@ -37,6 +46,15 @@ public static void tick(SectionBuilder parent, /** * Module headed by {@link SectionHeader#upperRule}; useful for * clean side-rail layouts. + * + * @param parent the section builder the module is appended to + * @param name node name used in snapshots and layout graph paths + * @param title the section title text + * @param theme the active theme supplying palette, typography, and spacing + * @param titleStyle text style for the label + * @param ruleColor colour of the rule beneath the label + * @param ruleWidth width in points of the rule beneath the label + * @param body callback drawing the section body */ public static void upperRule(SectionBuilder parent, String name, diff --git a/src/main/java/com/demcha/compose/document/templates/invoice/spec/InvoiceSpec.java b/src/main/java/com/demcha/compose/document/templates/invoice/spec/InvoiceSpec.java index 9158456e..38cd6db4 100644 --- a/src/main/java/com/demcha/compose/document/templates/invoice/spec/InvoiceSpec.java +++ b/src/main/java/com/demcha/compose/document/templates/invoice/spec/InvoiceSpec.java @@ -181,21 +181,61 @@ public static final class Builder { private Builder() { } - /** @param value invoice number @return this builder */ + /** + * Sets the invoice number. + * + * @param value invoice number + * @return this builder + */ public Builder invoiceNumber(String value) { this.invoiceNumber = value; return this; } - /** @param value issue date @return this builder */ + /** + * Sets the issue date. + * + * @param value issue date + * @return this builder + */ public Builder issueDate(String value) { this.issueDate = value; return this; } - /** @param value due date @return this builder */ + /** + * Sets the due date. + * + * @param value due date + * @return this builder + */ public Builder dueDate(String value) { this.dueDate = value == null ? "" : value; return this; } - /** @param value sender party @return this builder */ + /** + * Sets the sender party. + * + * @param value sender party + * @return this builder + */ public Builder fromParty(Party value) { this.fromParty = value; return this; } - /** @param value recipient party @return this builder */ + /** + * Sets the recipient party. + * + * @param value recipient party + * @return this builder + */ public Builder billToParty(Party value) { this.billToParty = value; return this; } - /** @param item line item @return this builder */ + /** + * Adds a line item. + * + * @param item line item + * @return this builder + */ public Builder lineItem(LineItem item) { this.lineItems.add(item); return this; } - /** @param row summary row @return this builder */ + /** + * Adds a summary row. + * + * @param row summary row + * @return this builder + */ public Builder summaryRow(SummaryRow row) { this.summaryRows.add(row); return this; } - /** @param note footer note @return this builder */ + /** + * Adds a footer note. + * + * @param note footer note + * @return this builder + */ public Builder note(String note) { if (note != null) this.notes.add(note); return this; } /** diff --git a/src/main/java/com/demcha/compose/document/templates/proposal/spec/ProposalSpec.java b/src/main/java/com/demcha/compose/document/templates/proposal/spec/ProposalSpec.java index b45b9682..ade8e6c0 100644 --- a/src/main/java/com/demcha/compose/document/templates/proposal/spec/ProposalSpec.java +++ b/src/main/java/com/demcha/compose/document/templates/proposal/spec/ProposalSpec.java @@ -152,17 +152,47 @@ public static final class Builder { private Builder() { } - /** @param value title @return this builder */ + /** + * Sets the proposal title. + * + * @param value title + * @return this builder + */ public Builder title(String value) { this.title = value; return this; } - /** @param value sender party @return this builder */ + /** + * Sets the sender party. + * + * @param value sender party + * @return this builder + */ public Builder fromParty(Party value) { this.fromParty = value; return this; } - /** @param value receiving party @return this builder */ + /** + * Sets the receiving party. + * + * @param value receiving party + * @return this builder + */ public Builder toParty(Party value) { this.toParty = value; return this; } - /** @param section content section @return this builder */ + /** + * Adds a content section. + * + * @param section content section + * @return this builder + */ public Builder section(Section section) { this.sections.add(section); return this; } - /** @param row pricing row @return this builder */ + /** + * Adds a pricing row. + * + * @param row pricing row + * @return this builder + */ public Builder pricingRow(PricingRow row) { this.pricingRows.add(row); return this; } - /** @param note footer note @return this builder */ + /** + * Sets the footer note. + * + * @param note footer note + * @return this builder + */ public Builder footerNote(String note) { this.footerNote = note == null ? "" : note; return this; } /** diff --git a/src/main/java/com/demcha/compose/document/templates/widgets/CardWidget.java b/src/main/java/com/demcha/compose/document/templates/widgets/CardWidget.java index 34e4cb5b..24e17b74 100644 --- a/src/main/java/com/demcha/compose/document/templates/widgets/CardWidget.java +++ b/src/main/java/com/demcha/compose/document/templates/widgets/CardWidget.java @@ -23,6 +23,15 @@ public final class CardWidget { private CardWidget() { } + /** + * Renders the card as a nested section under {@code parent}, + * applying the visual shell and then the supplied body. + * + * @param parent parent section receiving the card + * @param name node name used in snapshots and layout graph paths + * @param style visual shell options; null falls back to defaults + * @param content callback that populates the card body + */ public static void render(SectionBuilder parent, String name, Style style, @@ -44,6 +53,11 @@ public static void render(SectionBuilder parent, * section. Visual shell behaves identically to the * {@link #render(SectionBuilder, String, Style, Consumer)} * variant. + * + * @param flow page flow receiving the card + * @param name node name used in snapshots and layout graph paths + * @param style visual shell options; null falls back to defaults + * @param content callback that populates the card body */ public static void render(PageFlowBuilder flow, String name, @@ -75,6 +89,12 @@ private static void applyStyle(SectionBuilder card, Style style) { /** * Visual shell options for {@link CardWidget}. + * + * @param spacing vertical spacing between children + * @param padding inner padding + * @param fillColor optional background fill + * @param stroke optional uniform border stroke + * @param cornerRadius optional render-only corner radius */ public record Style(double spacing, DocumentInsets padding, @@ -82,6 +102,10 @@ public record Style(double spacing, DocumentStroke stroke, DocumentCornerRadius cornerRadius) { + /** + * Validates that spacing is finite and non-negative and + * normalises a null padding to zero insets. + */ public Style { if (Double.isNaN(spacing) || Double.isInfinite(spacing) || spacing < 0) { @@ -91,10 +115,18 @@ public record Style(double spacing, padding = padding == null ? DocumentInsets.zero() : padding; } + /** + * Creates a builder seeded with conservative defaults. + * + * @return a mutable builder seeded with conservative defaults + */ public static Builder builder() { return new Builder(); } + /** + * Fluent builder for {@link Style}. + */ public static final class Builder { private double spacing; private DocumentInsets padding = DocumentInsets.zero(); @@ -105,36 +137,77 @@ public static final class Builder { private Builder() { } + /** + * Sets the vertical spacing between children. + * + * @param value vertical spacing between children + * @return this builder for chaining + */ public Builder spacing(double value) { this.spacing = value; return this; } + /** + * Sets the inner padding. + * + * @param value inner padding + * @return this builder for chaining + */ public Builder padding(DocumentInsets value) { this.padding = value; return this; } + /** + * Sets the optional background fill. + * + * @param value optional background fill + * @return this builder for chaining + */ public Builder fillColor(DocumentColor value) { this.fillColor = value; return this; } + /** + * Sets the optional uniform border stroke. + * + * @param value optional uniform border stroke + * @return this builder for chaining + */ public Builder stroke(DocumentStroke value) { this.stroke = value; return this; } + /** + * Sets the optional render-only corner radius from a raw value. + * + * @param value corner radius in points + * @return this builder for chaining + */ public Builder cornerRadius(double value) { this.cornerRadius = DocumentCornerRadius.of(value); return this; } + /** + * Sets the optional render-only corner radius. + * + * @param value optional render-only corner radius + * @return this builder for chaining + */ public Builder cornerRadius(DocumentCornerRadius value) { this.cornerRadius = value; return this; } + /** + * Builds the configured {@link Style}. + * + * @return a new {@code Style} carrying the configured shell options + */ public Style build() { return new Style(spacing, padding, fillColor, stroke, cornerRadius); diff --git a/src/main/java/com/demcha/compose/document/templates/widgets/TableWidget.java b/src/main/java/com/demcha/compose/document/templates/widgets/TableWidget.java index 940d60cf..456e7c2e 100644 --- a/src/main/java/com/demcha/compose/document/templates/widgets/TableWidget.java +++ b/src/main/java/com/demcha/compose/document/templates/widgets/TableWidget.java @@ -180,6 +180,11 @@ public record Style(String name, Double lineSpacing, double widthAdjustment) { + /** + * Normalises a blank name to {@code "TemplateTable"} and a null + * padding to zero insets, and validates the column count, + * line spacing, and width adjustment. + */ public Style { name = (name == null || name.isBlank()) ? "TemplateTable" : name; if (columns < 1) { @@ -205,6 +210,8 @@ public record Style(String name, } /** + * Creates a new style builder. + * * @return mutable builder seeded with conservative defaults */ public static Builder builder() { @@ -228,56 +235,122 @@ public static final class Builder { private Builder() { } + /** + * Sets the semantic table node name. + * + * @param value semantic table node name + * @return this builder for chaining + */ public Builder name(String value) { this.name = value; return this; } + /** + * Sets the fixed column count. + * + * @param value fixed column count + * @return this builder for chaining + */ public Builder columns(int value) { this.columns = value; return this; } + /** + * Sets the padding inside every cell. + * + * @param value padding inside every cell + * @return this builder for chaining + */ public Builder cellPadding(DocumentInsets value) { this.cellPadding = value; return this; } + /** + * Sets the cell border stroke from a colour and width. + * + * @param color border colour + * @param width border width in points + * @return this builder for chaining + */ public Builder border(DocumentColor color, double width) { this.cellStroke = DocumentStroke.of(color, width); return this; } + /** + * Sets the optional cell border stroke. + * + * @param value optional border stroke + * @return this builder for chaining + */ public Builder cellStroke(DocumentStroke value) { this.cellStroke = value; return this; } + /** + * Sets the optional default fill for every cell. + * + * @param value optional default fill for every cell + * @return this builder for chaining + */ public Builder cellFillColor(DocumentColor value) { this.cellFillColor = value; return this; } + /** + * Sets the optional fill for alternating rows. + * + * @param value optional fill for alternating rows + * @return this builder for chaining + */ public Builder zebraFillColor(DocumentColor value) { this.zebraFillColor = value; return this; } + /** + * Sets the optional text style override. + * + * @param value optional text style override + * @return this builder for chaining + */ public Builder textStyle(DocumentTextStyle value) { this.textStyle = value; return this; } + /** + * Sets the optional line spacing override. + * + * @param value optional line spacing override + * @return this builder for chaining + */ public Builder lineSpacing(Double value) { this.lineSpacing = value; return this; } + /** + * Sets the value subtracted before splitting width into columns. + * + * @param value value subtracted before splitting width into columns + * @return this builder for chaining + */ public Builder widthAdjustment(double value) { this.widthAdjustment = value; return this; } + /** + * Builds the configured {@link Style}. + * + * @return a new {@code Style} carrying the configured table options + */ public Style build() { return new Style(name, columns, cellPadding, cellStroke, cellFillColor, zebraFillColor, textStyle, diff --git a/src/main/java/com/demcha/compose/document/templates/widgets/TimelineAxisWidget.java b/src/main/java/com/demcha/compose/document/templates/widgets/TimelineAxisWidget.java index 6753f62b..a5794810 100644 --- a/src/main/java/com/demcha/compose/document/templates/widgets/TimelineAxisWidget.java +++ b/src/main/java/com/demcha/compose/document/templates/widgets/TimelineAxisWidget.java @@ -62,6 +62,9 @@ private TimelineAxisWidget() { * Renders the timeline axis using the supplied {@link Style}. The * total height is implied by {@code segmentCount * segmentLength * + (segmentCount - 1) * markerSize}. + * + * @param host host section receiving the axis + * @param style configured style; null falls back to defaults */ public static void render(SectionBuilder host, Style style) { Objects.requireNonNull(host, "host"); @@ -171,6 +174,10 @@ public record Style(Marker marker, double lineThickness, DocumentInsets padding) { + /** + * Normalises the marker and clamps sizes, counts, and thickness + * to their valid ranges. + */ public Style { marker = marker == null ? Marker.CIRCLE : marker; markerSize = Math.max(0.0, markerSize); @@ -180,10 +187,20 @@ public record Style(Marker marker, padding = padding == null ? DocumentInsets.zero() : padding; } + /** + * Creates a builder seeded with conservative defaults. + * + * @return a mutable builder seeded with conservative defaults + */ public static Builder builder() { return new Builder(); } + /** + * Creates a builder pre-populated with this style's values. + * + * @return a mutable builder seeded from this style + */ public Builder toBuilder() { return new Builder() .marker(marker) @@ -197,6 +214,9 @@ public Builder toBuilder() { .padding(padding); } + /** + * Fluent builder for {@link Style}. + */ public static final class Builder { private Marker marker = Marker.CIRCLE; private double markerSize = 7.0; @@ -211,51 +231,110 @@ public static final class Builder { private Builder() { } + /** + * Sets the marker shape drawn between segments. + * + * @param value shape drawn between segments + * @return this builder for chaining + */ public Builder marker(Marker value) { this.marker = value; return this; } + /** + * Sets the marker size. + * + * @param value diameter (CIRCLE) or side length (SQUARE) + * @return this builder for chaining + */ public Builder markerSize(double value) { this.markerSize = value; return this; } + /** + * Sets the marker fill colour. + * + * @param value fill colour of the marker + * @return this builder for chaining + */ public Builder markerFillColor(DocumentColor value) { this.markerFillColor = value; return this; } + /** + * Sets the marker stroke. + * + * @param value stroke around the marker + * @return this builder for chaining + */ public Builder markerStroke(DocumentStroke value) { this.markerStroke = value; return this; } + /** + * Sets the length of each vertical line segment. + * + * @param value length of each vertical line segment + * @return this builder for chaining + */ public Builder segmentLength(double value) { this.segmentLength = value; return this; } + /** + * Sets the number of segments. + * + * @param value number of segments (at least 1) + * @return this builder for chaining + */ public Builder segmentCount(int value) { this.segmentCount = value; return this; } + /** + * Sets the colour of every line segment. + * + * @param value colour of every line segment + * @return this builder for chaining + */ public Builder lineColor(DocumentColor value) { this.lineColor = value; return this; } + /** + * Sets the thickness of every line segment. + * + * @param value thickness of every line segment + * @return this builder for chaining + */ public Builder lineThickness(double value) { this.lineThickness = value; return this; } + /** + * Sets the inset applied to the host section before drawing. + * + * @param value inset applied to the host section before any drawing + * @return this builder for chaining + */ public Builder padding(DocumentInsets value) { this.padding = value; return this; } + /** + * Builds the configured {@link Style}. + * + * @return a new {@code Style} carrying the configured axis options + */ public Style build() { return new Style(marker, markerSize, markerFillColor, markerStroke, segmentLength, segmentCount,