How to extract JavaDoc comments from the source files

Question

How do I extract the JavaDoc comments from the Java source files ? as well as format them as I want to?

Answer 1

See the Doclets section of Javadoc Tool Home Page for the standard approach.

Doclets The standard doclet generates HTML and is built into the Javadoc tool. Other doclets that Java Software has developed are listed here. ..

See particularly Example - Subclassing the Standard Doclet & the Doclet API.

Answer 2

Generate them using: javadoc *.java and then rewrite stylesheet.css as you want...

Answer 3

As an alternative, you might consider a class I wrote, called FilteredLineIterator, which can be used to scrape all JavaDoc lines from a source file.

(This answer is similar to the one I wrote in this question.)

A FilteredLineIterator is a string iterator that filters (keeps or suppresses) the elements in another iterator, based on the "entities" (single line, block, and "stealth" blocks) in which each line exists. Kept lines can be optionally modified.

(FilteredLineIterator is part of XBN-Java. Jars can be downloaded here.)

Example top and setup:

   import  com.github.xbn.linefilter.FilteredLineIterator;
   import  com.github.xbn.linefilter.KeepUnmatched;
   import  com.github.xbn.linefilter.Returns;
   import  com.github.xbn.linefilter.entity.BlockEntity;
   import  com.github.xbn.linefilter.entity.EntityRequired;
   import  com.github.xbn.linefilter.entity.KeepMatched;
   import  com.github.xbn.linefilter.entity.NewBlockEntityFor;
   import  com.github.xbn.linefilter.entity.NewStealthBlockEntityFor;
   import  com.github.xbn.linefilter.entity.StealthBlockEntity;
   import  com.github.xbn.testdev.GetFromCommandLineAtIndex;
   import  com.github.xbn.util.IncludeJavaDoc;
   import  java.util.Iterator;
/**
  <P>{@code java ExtractAllJavaDocBlockTextRaw examples\com\github\xbn\examples\linefilter\JavaClassWithOneCommentAndTwoJavaDocBlocks_input.txt}</P>
 **/
public class ExtractAllJavaDocBlockTextRaw  {
  public static final void main(String[] cmd_lineParams)  {
     //Example setup:
        Iterator<String> rawInputLineItr = GetFromCommandLineAtIndex.fileLineIterator(
           cmd_lineParams, 0,
           null);   //debugPath

The main section starts below. JavaDoc blocks are defined as a block entity, where only the mid (not the start or end) lines are kept. To prevent incorrect "end line found before block open" errors--since the end line for both JavaDoc and "normal" (non-JavaDoc) multi-line comments is */--a stealth block for normal multi-line comments must be declared.

The input's raw line iterator, and both entities, are fed to the filtered line iterator.

     StealthBlockEntity javaMlcBlock = NewStealthBlockEntityFor.javaComment(
        "comment", IncludeJavaDoc.NO,
        null,       //dbgStart (on=System.out, off=null)
        null,       //dbgEnd
        KeepMatched.NO, EntityRequired.YES, null,
        null);      //dbgLineNums

     BlockEntity javaDocBlock = NewBlockEntityFor.javaDocComment_Cfg(
        "doccomment",
        null,       //dbgStart
        null,       //dbgEnd
        EntityRequired.YES, null,
        null).      //dbgLineNums
        keepMidsOnly().build();

     FilteredLineIterator filteredItr = new FilteredLineIterator(
        rawInputLineItr, Returns.KEPT, KeepUnmatched.NO,
        null, null,    //dbgEveryLine and its line-range
        javaMlcBlock, javaDocBlock);

     while(filteredItr.hasNext())  {
        System.out.println(filteredItr.next());
     }
  }
}

Output (the input file is at the bottom of this answer-post):

        <P>The main class JavaDoc block.</P>
      <P>Constructor JavaDoc block</P>
      * <P>Function JavaDoc block.</P>

      * <P>This function does some stuff.</P>

      * <P>Lots and lots of stuff.</P>

To strip the optional asterisks from each line, including any preceding whitespace, add a "mid line alterer" to the JavaDoc block entity:

TextLineAlterer asteriskStripper = NewTextLineAltererFor.replacement(
   Pattern.compile("[ \t]*(?:\\*[ \t]*)?(.*)"), "$1",
   ReplacedInEachInput.FIRST,
   null,       //debug
   null);

Add the alterer to the block entity by changing keepMidsOnly().build(); to

midAlter(asteriskStripper).keepMidsOnly().build();

Output:

<P>The main class JavaDoc block.</P>
<P>Constructor JavaDoc block</P>
<P>Function JavaDoc block.</P>

<P>This function does some stuff.</P>

<P>Lots and lots of stuff.</P>

The input file:

/*
   A Java comment block.
 */
package  fully.qualified.package.name;
/**
   <P>The main class JavaDoc block.</P>
 */
public class StayClassy  {
   /**
      <P>Constructor JavaDoc block</P>
    */
   public StayClassy()  {
      //Do stuff
   }
   /**
      * <P>Function JavaDoc block.</P>

      * <P>This function does some stuff.</P>

      * <P>Lots and lots of stuff.</P>
    */
   public void doStuff()  {
   }
}