Since Java 1.2, the javadoc command has generated neatly formatted documentation. The tool comes with its own API which allows customised output. The relevant classes are under the com.sun package hierarchy, and located in JRE_HOME/lib/tools.jar, which typically will have to be included manually. E.g. it can be found under /usr/lib/jvm/java-8-openjdk-amd64/lib/tools.jar.

Note that the Sun Doclet API is getting long in th tooth, and is already slated for replacement in Java 9, through the “Simplified Doclet API” in JDK Enhancement Proposal 221. Java 9 is planned for Q3 2017.

Meanwhile, the old Doclet API still does an OK job of parsing JavaDoc in .java source files. If the goal is to parse, rather than to produce the standard formatted JavaDoc, it’s useful to start the process pragmatically. Than can be achieved through its main class, com.sun.tools.javadoc.Main:

    Main.execute("MyName", SunDocletPrinter.class.getName(),
        new String[] { "com/rememberjava/doc/SunDocletPrinter.java" });

The execute() method will invoke the public static method start() in the specified class. In the example below, a few of the main JavaDoc entities are enumerated. The direct output can be see the block below. The class which is parsed is the example class itself, included at the bottom of this article.

  public static boolean start(RootDoc root) {
    System.out.println("--- start");

    for (ClassDoc classDoc : root.classes()) {
      System.out.println("Class: " + classDoc);

      // Class annotations
      for (AnnotationDesc annotation : classDoc.annotations()) {
        System.out.println("  Annotation: " + annotation);
      }

      // Class JavaDoc tags
      for (Tag tag : classDoc.tags()) {
        System.out.println("  Class tag:" + tag.name() + "=" + tag.text());
      }

      // Global constants and fields
      for (FieldDoc fieldDoc : classDoc.fields()) {
        System.out.println("  Field: " + fieldDoc);
      }

      // Methods
      for (MethodDoc methodDoc : classDoc.methods()) {
        System.out.println("  Method: " + methodDoc);

        // Method annotations
        for (AnnotationDesc annotation : methodDoc.annotations()) {
          System.out.println("    Annotation: " + annotation);
        }

        // Method JavaDoc comment (without parameters)
        System.out.println("    Doc: " + methodDoc.commentText());

        // Method JavaDoc (only the first sentence)
        for (Tag tag : methodDoc.firstSentenceTags()) {
          System.out.println("    Tag: " + tag);
        }

        // Method parameters (without return)
        for (ParamTag paramTag : methodDoc.paramTags()) {
          System.out.println("    Param:" + paramTag.parameterName() + "=" + paramTag.parameterComment());
        }

        // The full method JavaDoc text
        System.out.println("    Raw doc:\n" + methodDoc.getRawCommentText());
      }
    }

    System.out.println("--- the end");
    return true;
  }

- start main
Loading source file com/rememberjava/doc/SunDocletPrinter.java...
Constructing Javadoc information...
--- start
Class: com.rememberjava.doc.SunDocletPrinter
  Annotation: @java.lang.Deprecated
  Class tag:@author=Bob
  Class tag:@since=123
  Class tag:@custom=Custom Annotation
  Class tag:@see="http://docs.oracle.com/javase/6/docs/technotes/guides/javadoc/doclet/overview.html"
  Field: com.rememberjava.doc.SunDocletPrinter.SOME_FIELD
  Method: com.rememberjava.doc.SunDocletPrinter.main(java.lang.String[])
    Annotation: @java.lang.SuppressWarnings("Test")
    Doc: 
    Raw doc:
 @see "http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/standard-doclet.html"

  Method: com.rememberjava.doc.SunDocletPrinter.start(com.sun.javadoc.RootDoc)
    Doc: This method processes everything. And there's more to it.
    Tag: Text:This method processes everything.
    Param:root=the root element
    Raw doc:
 This method processes everything. And there's more to it.
 
 @param root
          the root element
 @return returns true

--- the end
- done execute

Here is full file, which also shows the JavaDoc the example operates on.

SunDocletPrinter.java
GitHub Raw
/* Copyright rememberjava.com. Licensed under GPL 3. See http://rememberjava.com/license */
package com.rememberjava.doc;

import com.sun.javadoc.AnnotationDesc;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.FieldDoc;
import com.sun.javadoc.MethodDoc;
import com.sun.javadoc.ParamTag;
import com.sun.javadoc.RootDoc;
import com.sun.javadoc.Tag;
import com.sun.tools.javadoc.Main;

/**
 * Example self-contained Doclet which prints raw text.
 * 
 * @author Bob
 * @since 123
 * @custom Custom Annotation
 * @see "http://docs.oracle.com/javase/6/docs/technotes/guides/javadoc/doclet/overview.html"
 */
@Deprecated
public class SunDocletPrinter {

  public static String SOME_FIELD;

  /**
   * @see "http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/standard-doclet.html"
   */
  @SuppressWarnings(value = { "Test" })
  public static void main(String[] args) {
    System.out.println("- start main");
    Main.execute("MyName", SunDocletPrinter.class.getName(),
        new String[] { "com/rememberjava/doc/SunDocletPrinter.java" });
    System.out.println("- done execute");
  }

  /**
   * This method processes everything. And there's more to it.
   * 
   * @param root
   *          the root element
   * @return returns true
   */
  public static boolean start(RootDoc root) {
    System.out.println("--- start");

    for (ClassDoc classDoc : root.classes()) {
      System.out.println("Class: " + classDoc);

      // Class annotations
      for (AnnotationDesc annotation : classDoc.annotations()) {
        System.out.println("  Annotation: " + annotation);
      }

      // Class JavaDoc tags
      for (Tag tag : classDoc.tags()) {
        System.out.println("  Class tag:" + tag.name() + "=" + tag.text());
      }

      // Global constants and fields
      for (FieldDoc fieldDoc : classDoc.fields()) {
        System.out.println("  Field: " + fieldDoc);
      }

      // Methods
      for (MethodDoc methodDoc : classDoc.methods()) {
        System.out.println("  Method: " + methodDoc);

        // Method annotations
        for (AnnotationDesc annotation : methodDoc.annotations()) {
          System.out.println("    Annotation: " + annotation);
        }

        // Method JavaDoc comment (without parameters)
        System.out.println("    Doc: " + methodDoc.commentText());

        // Method JavaDoc (only the first sentence)
        for (Tag tag : methodDoc.firstSentenceTags()) {
          System.out.println("    Tag: " + tag);
        }

        // Method parameters (without return)
        for (ParamTag paramTag : methodDoc.paramTags()) {
          System.out.println("    Param:" + paramTag.parameterName() + "=" + paramTag.parameterComment());
        }

        // The full method JavaDoc text
        System.out.println("    Raw doc:\n" + methodDoc.getRawCommentText());
      }
    }

    System.out.println("--- the end");
    return true;
  }
}