EN
RU
ES
ZH
FR
DE
PT
AR
HI
Introduction: Why Documentation is Code
\nAt the initial level of Java project development, documentation is often perceived as a formality. However, at an advanced level, it transforms into a full-fledged product that requires an architectural approach, automation, and strict quality standards. Poorly written documentation can negate the advantages of the cleanest code, while high-quality documentation reduces the onboarding time for new developers by 2-3 times and serves as the single source of truth for external integrations.
\nIn this article, we will explore advanced techniques for writing documentation for Java projects that go beyond simple comments. You will learn how to use JavaDoc with custom tags, integrate documentation into CI/CD, apply AsciiDoc for complex guides, and automatically test code examples in documentation.
1. JavaDoc on Steroids: Custom Tags and the Doclet API
\nStandard JavaDoc is the foundation, but advanced levels require customization. For example, you can create custom tags for documenting business requirements, links to Jira tasks, or API versions.
Creating Custom Tags
\nUse the @customTag annotation or configuration in pom.xml (for Maven) to add new tags. Example:
/**\n * Performs user input validation.\n *\n * @businessRule The email field must comply with RFC 5322\n * @jiraTicket PROJ-1234\n * @since 2.1.0\n * @param input string for validation\n * @return true if the input is valid\n */\npublic boolean validateEmail(String input) {\n // implementation\n}To generate documentation with custom tags, add the following to the Maven plugin:
\n<plugin>\n <groupId>org.apache.maven.plugins</groupId>\n <artifactId>maven-javadoc-plugin</artifactId>\n <configuration>\n <tags>\n <tag>\n <name>businessRule</name>\n <placement>a</placement>\n <head>Business Rule</head>\n </tag>\n <tag>\n <name>jiraTicket</name>\n <placement>a</placement>\n <head>Jira Ticket</head>\n </tag>\n </tags>\n </configuration>\n</plugin>Doclet API for Generating Non-Standard Formats
\nIf standard HTML is not enough, write your own Doclet. This allows you to generate documentation in PDF, Markdown, or even JSON format for external systems.
\npublic class CustomDoclet extends Doclet {\n @Override\n public boolean run(DocletEnvironment environment) {\n // Get all classes\n for (TypeElement element : environment.getIncludedTypeElements()) {\n // Generate Markdown or another format\n System.out.println("# " + element.getSimpleName());\n for (ExecutableElement method : ElementFilter.methodsIn(element.getEnclosedElements())) {\n System.out.println("## " + method.getSimpleName());\n System.out.println(method.getDocComment());\n }\n }\n return true;\n }\n}Run your Doclet via Maven: mvn javadoc:javadoc -Ddoclet=com.example.CustomDoclet.
2. AsciiDoc: Documentation as Code (Docs-as-Code)
\nFor complex guides, architectural descriptions, and API references, JavaDoc is not suitable. This is where AsciiDoc comes to the rescue — a text format that is easily versioned in Git, supports code insertion, tables, diagrams, and conditional blocks.
Integration with Maven
\nUse the asciidoctor-maven-plugin to build documentation directly from the repository:
Blogs
Book Recommendations
Read also
