Doclets: Decipher and Document Java Code Easily

Doclets: Decipher and Document Java Code Easily

rying to understand the logic of an unfamiliar Java project can be taxing. Learning the project’s code is even more difficult when there is no knowledge transfer from the developer(s) who developed it. Increasingly, this is becoming a common task for developers, which isn’t necessarily bad news because it provides a great opportunity for job security. A developer becomes indispensable when he or she is the knowledge source for existing projects.

Doclets, a new addition to Java SE 6, is very handy for reviewing existing source code and mastering the logic behind it. Doclet is a starting class for defining the entry point methods of the package com.sun.javadoc. The Doclet API is an extension for Javadoc, the original Java tool that automatically creates documentation from source code files. The Doclet API provides various features for customizing documentation output and offers architectural means for embedding the crux of source code logic for new projects inside custom tags—the proper way to document logic. This enables future developers to simply review the custom tags documentation to understand the logic instead of scouring through the entire documentation.

The predecessor to Doclets—Javadoc—has been around since Java came out, but it offered developers no control over the output it generated nor did it provide customization features. Javadoc specifies a fixed set of tags that developers can use to document code logic and generates boilerplate documentation in HTML. It also requires the developer to keep all code comments up to date—an easy task to forget. If the code is missing all the Javadoc-specified tags—a common scenario because in tight development schedules documenting the code takes the lowest priority, refactoring the program requires as much time as reading the code itself.

Comparing the old with the new:

  • Javadoc merely looks for tags to generate documentation; Doclets compile the source files before generating the documentation.
  • Doclets stop processing if they encounter any errors at compile time; Javadoc lets you generate documentation for un-compiled code.

Another documentation tool, Classdoc, is an open source project for generating documentation for missing source files from compiled code. However, it has its own limitations:

  • It is limited in displaying inner classes.
  • It doesn’t provide hyperlinks.
  • It provides only the signatures of methods, so developers must use a decompiler to understand the code in Classdoc output.

This article introduces the main classes and methods to get started with Doclets and demonstrates its features with practical examples.

Doclets in Depth
A simple Doclet can scan through all classes and print only the fields, methods, and super class information—very handy for segregating the main logic-processing classes from the support classes. To make a developer’s life even easier, the Doclet API’s Doc class has methods to retrieve the position of a particular line in a given file. in the source code download is an example of a simple Doclet. It walks through each class and prints all the methods and their method signatures. However, the Doclet API provides various additional classes and methods to customize processing further. All custom Doclets, such as those included in the source code download, must extend from com.sun.javadoc.Doclet and implement the following start method:

public static boolean start(RootDoc root)
Figure 1. Output from Running Doclet Example: The –private option processes the private methods of the class, while the –Doclet option forces Javadoc to use the example Doclet.

The root.classes() method of RootDoc grants access to an array of ClassDocs, which in turn could be used to navigate the class structures (for example, methods, constructors, fields, etc.). The typeParamTags() method of the ClassDoc or MethodDoc interfaces retrieves all the existing parameter tags documented in the code. The MethodDoc.tags(String tagName) method allows you to retrieve your custom tags by passing a custom tag name.

Run the Doclets
To run the Doclets in the source code download, take the following steps:

  1. Include tools.jar in your classpath.
  2. In the command prompt, type the following commands:
    $>javadoc -private -doclet MyDocletMissingDocumentation -docletpath .

The –private option processes the private methods of the class. The –Doclet option forces Javadoc to use your Doclet as opposed to the standard Doclet. Figure 1 shows the output.

Architectural Usage
The Doclet API comes in very handy for peer code reviews as well. Peer reviewers could write a custom Doclet, and prior to reviewing the code, they could run it on existing projects to ensure that the code is properly documented with all the comment tags. This saves the coders and reviewers a lot of time.

Figure 2. The Output from Even though other tags are present in, only the documentation related to custom tags is retrieved. in the source code download demonstrates how you can define the documentation of special logic in custom tags and how a custom Doclet can print out only the classes and methods that have these custom tags. For example, here is the output from, a sample file that is run through

	/**	 * @myTag getAge() returns 2 years less for women	 * @myTag getAge() returns actual age for men	 */

Even though other tags are present in, only the documentation related to custom tags is retrieved (see Figure 2).

Figure 3. The Output from lists all the methods that are missing documentation, methods that have empty tags, and methods that have duplicate tags.

Another Doclet example,, lists all the methods that are missing documentation, methods that have empty tags, and methods that have duplicate tags (see Figure 3).

The Doclet could be enhanced to look for unnecessary documentation, multiple tags, and so on, and basically to automate the entire peer-review process. For well-defined software development lifecycles, use cases could be tied to code documentation using custom tags.

Doclets Needed Now More Than Ever
With all the IT outsourcing today, code written in one country often is maintained by people in other countries. As such, documentation is no longer an option, but rather a requirement. In response, various Doclet support tools are available to make documentation generation more accessible. For example, MIF Doclet output documentation in PDF format and XDoclets generate code based on tag information.

Share the Post:
XDR solutions

The Benefits of Using XDR Solutions

Cybercriminals constantly adapt their strategies, developing newer, more powerful, and intelligent ways to attack your network. Since security professionals must innovate as well, more conventional endpoint detection solutions have evolved

AI is revolutionizing fraud detection

How AI is Revolutionizing Fraud Detection

Artificial intelligence – commonly known as AI – means a form of technology with multiple uses. As a result, it has become extremely valuable to a number of businesses across

AI innovation

Companies Leading AI Innovation in 2023

Artificial intelligence (AI) has been transforming industries and revolutionizing business operations. AI’s potential to enhance efficiency and productivity has become crucial to many businesses. As we move into 2023, several

data fivetran pricing

Fivetran Pricing Explained

One of the biggest trends of the 21st century is the massive surge in analytics. Analytics is the process of utilizing data to drive future decision-making. With so much of

kubernetes logging

Kubernetes Logging: What You Need to Know

Kubernetes from Google is one of the most popular open-source and free container management solutions made to make managing and deploying applications easier. It has a solid architecture that makes

ransomware cyber attack

Why Is Ransomware Such a Major Threat?

One of the most significant cyber threats faced by modern organizations is a ransomware attack. Ransomware attacks have grown in both sophistication and frequency over the past few years, forcing

data dictionary

Tools You Need to Make a Data Dictionary

Data dictionaries are crucial for organizations of all sizes that deal with large amounts of data. they are centralized repositories of all the data in organizations, including metadata such as