Reputation: 3942

How to extract JavaDoc comments from the source files

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

Upvotes: 8

Answers (3)

aliteralmind

Reputation: 20163

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()  {
   }
}

Upvotes: 0