Getting Started with DocFlex/Doclet — Setup, Examples, Best Practices

Advanced DocFlex/Doclet Techniques: Templates, Custom Tags, and Automation

Templates

• Use the DocFlex Template Designer to build visual, reusable templates (pages, blocks, tables, lists) rather than hand-coding output logic.
• Split concerns: create small templates for header/footer, type/class pages, member lists, and reuse with include/parameters.
• Parameterize templates with multi-valued and typed parameters (lists, booleans, strings) so a single template supports multiple output variants (framed HTML, single-file HTML, RTF, TXT).
• Render embedded HTML and images placed in doc-comments; templates can maptags to output image handling (paths, attributes, imagemaps).
• Keep format-neutral layouts (flows, paragraphs, tables) so the interpreter can target different formats without changing template semantics.

Custom Tags & Comment Processing

• Define and document project-specific custom block tags (e.g., @internal, @apiNote, @example) and use the Doclet/DocTrees API to parse DocCommentTree entries.
• In templates, use conditional inclusion/exclusion based on tags/annotations to omit or highlight elements (DocFlex standard templates support tag-driven exclusion).
• For programmatic doclet implementations, use the modern jdk.javadoc.doclet API: get DocTrees from DocletEnvironment, traverse DocCommentTree, and collect UnknownBlockTagTree nodes.
• Normalize tag values (key=value, lists, inline HTML) in a preprocessor or a Doclet-side scanner so templates receive clean, consistent data.

Automation & Build Integration

• Integrate DocFlex/Doclet runs into CI builds