Class AddJavaDoc

java.lang.Object
   |
   +----AddJavaDoc

public class AddJavaDoc

extends Object

Typical usage is:

    java iDoc.Tools -s -n -t %classname%.java >%classname%.idoc
    java AddJavaDoc %classname%.idoc %classname%.java [%header_file%]
 

The output (source with javadoc templates) PROVIDED NOTHING BAD HAPPENS is put into %classname%.jdoc. I strongly recommend verification (a compile and run of javadoc should be sufficient) before toasting the original.

If you run it on this class, it should look something like:

 C:\myJava>java iDoc.Tool -s -n -t AddJavaDoc.java >AddJavaDoc.idoc
 C:\myJava>java AddJavaDoc AddJavaDoc.idoc AddJavaDoc.java
 0  306 iDoc.Variable Title
 1  311  NONJAVADOC
 2  311  OBSOLETE iDoc.Method params obsoleteparm
 3  311 iDoc.Method Title
 4  311 iDoc.Method params missingparm returns
 

 C:\myJava>copy AddJavaDoc.jdoc t.java
 C:\myJava>javadoc -private -author -version -notree t.java
 

VERIFY THE .JDOC BEFORE COPYING BACK TO THE .JAVA -- I think this code is correct for now, but iDoc could change or an exception could happen and if you didn't verify it with at least a compile and a run of javadoc then you will lose your original source when copying the .jdoc to .java. Backups are always good too.

It should System.exit(1) if it encounters a problem, and you can test this in the shell (eg. IF ERRORLEVEL 1 in DOS) to see if it completed successfully. Again, there are no guarantees -- keep backups of your source.

Just as an example, here is the .BAT file I use.

 java iDoc.Tool -s -n -t %1.java >%1.idoc
 if errorlevel 1 goto :errorexit
 java AddJavaDoc %1.idoc %1.java c:\myjava\freeheader.txt
 if errorlevel 1 goto :errorexit
 copy %1.java %1.jbak
 if errorlevel 1 goto :errorexit
 copy %1.jdoc %1.java
 echo Completed...
 goto :exit
 :errorexit
 echo ERROR!!!
 :exit
 echo exiting.
 

Ideally, the source is available with this page by clicking on "the source".

Be sure to check AddJavaDoc's "home page" at http://parasol.cs.tamu.edu/people/jack/fromCS/java/AddJavaDoc/AddJavaDoc.html for updates.

Revisions:

• 06JUL98-jkp - updated to handle iDoc scanner exceptions and tabbed indentation
• 08JUL98-jkp - added interface support. can also now error on "/***" which I use a lot in C to denote major code blocks but causes all kinds of problems for iDoc when following lines don't begin with "*" (iDoc thinks, quite rightly, that it is in a javadoc comment) -- this feature is disabled by default.
• 13JUL98-jkp - updated link to iDoc 0.2b3. I haven't done any testing with 0.2b3 yet, but it looks like the output is exactly the same as 0.1b so I don't expect it to cause problems. If it does, try using v0.1b.

Version:

0.0004 13 Jul 1998

Author:

Jack Perdue j-perdue@tamu.edu si_slick@cy-net.net

authortag

customized javadoc author tag (hard-coded for now -- needs servicing)

BADCOMMENT

Disallowed comment starter (change if desired)

CLASSTITLE

code for iDoc unlabeled class error

dobadcommentcheck

Disable bad comment check.

errorcode

code for iDoc error

FILL

indicates user needs to provide info for javadoc

FILLNONJAVADOC

indicates user needs to service some unrecognized javadoc comments

FILLOBSOLETETAG

indicates user needs to service a parameter tag

IDOCCLASSTAG

iDoc class tag

IDOCCOMMENTTAG

iDoc comment tag

IDOCERRORTAG

iDoc error tag

IDOCINTERFACETAG

iDoc interface tag

IDOCMETHODTAG

iDoc method tag

IDOCMISSINGTAG

iDoc missing tag

IDOCNONJAVADOCTAG

iDoc non-javadoc comment tag

IDOCOBSOLETETAG

iDoc obsolete tag

IDOCPARAMTAG

iDoc param tag

IDOCRETURNTAG

iDoc return tag

IDOCSCANNEREXCEPTIONTAG

iDoc Scanner exception tag

IDOCVARIABLETAG

iDoc variable tag

INTERFACETITLE

code for iDoc unlabeled interface error

JAVADOCAUTHOR

javadoc author tag

JAVADOCENDCOMMENT

javadoc endcomment

JAVADOCMIDDLECOMMENT

javadoc middle comment

JAVADOCPARAM

javadoc parameter tag

JAVADOCRETURN

javadoc return tag

JAVADOCSTARTCOMMENT

javadoc start comment

JAVADOCVERSION

javadoc version tag

lineno

line number the errorcode occurred

MAXPARAMS

maximum number of parameters a method can have

MAXREADFORMARK

Error file size limit

METHODPARAMRETURN

code for iDoc method parameters and return error

METHODPARAMVOID

code for iDoc method parameters error

METHODTITLE

code for iDoc unlabeled method error

NONJAVADOC

code for iDoc non-javadoc comment error

OBSOLETETAG

code for iDoc obsolete parameter tag error

params

parameters for method

unjavadocumentedvariablefortesting

+XX+

VARIABLETITLE

code for iDoc unlabeled variable error

versiontag

customized javadoc version tag (hard-coded for now -- needs servicing)

AddJavaDoc(int, int, String[])

Constructs an iDoc errorcode entry (a future javadoc comment)

addJavaDocs(String, AddJavaDoc[], String[])

adds javadoc comments to source code

iDocErrors(String)

reads iDoc errorcode file

main(String[])

Adds javadoc comments to code.

parseError(String)

parses iDoc error

readHeaders(String)

reads header (copyright) file into buffer

sortErrors(AddJavaDoc[])

sorts errors by line number and type

swap(AddJavaDoc[], int, int)

swaps two iDoc errors

testAddJavaDoc(int)

NONJAVADOC OBSOLETETAG obsoleteparm +XX+ +XX+

toString()

converts an iDoc errorcode (future javadoc addition) to a string

 static int MAXREADFORMARK

Error file size limit

 static int MAXPARAMS

maximum number of parameters a method can have

 static final int CLASSTITLE

code for iDoc unlabeled class error

 static final int INTERFACETITLE

code for iDoc unlabeled interface error

 static final int VARIABLETITLE

code for iDoc unlabeled variable error

 static final int METHODTITLE

code for iDoc unlabeled method error

 static final int METHODPARAMVOID

code for iDoc method parameters error

 static final int METHODPARAMRETURN

code for iDoc method parameters and return error

 static final int NONJAVADOC

code for iDoc non-javadoc comment error

 static final int OBSOLETETAG

code for iDoc obsolete parameter tag error

 static String FILL

indicates user needs to provide info for javadoc

 static String FILLOBSOLETETAG

indicates user needs to service a parameter tag

 static String FILLNONJAVADOC

indicates user needs to service some unrecognized javadoc comments

 static String IDOCSCANNEREXCEPTIONTAG

iDoc Scanner exception tag

 static String IDOCCLASSTAG

iDoc class tag

 static String IDOCINTERFACETAG

iDoc interface tag

 static String IDOCVARIABLETAG

iDoc variable tag

 static String IDOCMETHODTAG

iDoc method tag

 static String IDOCERRORTAG

iDoc error tag

 static String IDOCNONJAVADOCTAG

iDoc non-javadoc comment tag

 static String IDOCCOMMENTTAG

iDoc comment tag

 static String IDOCMISSINGTAG

iDoc missing tag

 static String IDOCOBSOLETETAG

iDoc obsolete tag

 static String IDOCPARAMTAG

iDoc param tag

 static String IDOCRETURNTAG

iDoc return tag

 static final boolean dobadcommentcheck

Disable bad comment check. Change if desired. However, enabling will cause errors when processing this class.

 static final String BADCOMMENT

Disallowed comment starter (change if desired)

 static final String JAVADOCSTARTCOMMENT

javadoc start comment

 static final String JAVADOCMIDDLECOMMENT

javadoc middle comment

 static final String JAVADOCENDCOMMENT

javadoc endcomment

 static final String JAVADOCPARAM

javadoc parameter tag

 static final String JAVADOCRETURN

javadoc return tag

 static final String JAVADOCAUTHOR

javadoc author tag

 static final String JAVADOCVERSION

javadoc version tag

 static String authortag

customized javadoc author tag (hard-coded for now -- needs servicing)

 static String versiontag

customized javadoc version tag (hard-coded for now -- needs servicing)

 int lineno

line number the errorcode occurred

 int errorcode

code for iDoc error

 String params[]

parameters for method

 static final int unjavadocumentedvariablefortesting

+XX+

 public AddJavaDoc(int lineno,
                   int errorcode,
                   String params[])

Constructs an iDoc errorcode entry (a future javadoc comment)

Parameters:

lineno - line number in source where javadoc comments are needed

errorcode - type of iDoc error

params - method parameters (to generate lines like this one)

 public static void main(String args[])

Adds javadoc comments to code.

Parameters:

args - iDoc filename, source filename, header filename

 final int testAddJavaDoc(int missingparm)

NONJAVADOC OBSOLETETAG obsoleteparm +XX+ +XX+

Parameters:

missingparm - +XX+

Returns:

+XX+

 static String[] readHeaders(String headername)

reads header (copyright) file into buffer

Parameters:

headername - name of header file

Returns:

buffer containing text of header file

 public static AddJavaDoc parseError(String line)

parses iDoc error

Parameters:

line - line of text from iDoc errorcode listing

Returns:

a iDoc errorcode (future javadoc addition)

 static AddJavaDoc[] iDocErrors(String idocname)

reads iDoc errorcode file

Parameters:

idocname - name of iDoc errorcode listing

Returns:

list of iDoc errors (future javadoc additions)

 static void addJavaDocs(String srcname,
                         AddJavaDoc errors[],
                         String headers[])

adds javadoc comments to source code

Parameters:

srcname - name of source code (.java) file

errors - list of iDoc errors (future javadoc additions)

headers - new header for source file

 static void swap(AddJavaDoc errors[],
                  int i,
                  int j)

swaps two iDoc errors

Parameters:

errors - list of iDoc errors

i - errorcode to swap

j - errorcode to swap

 static void sortErrors(AddJavaDoc errors[])

sorts errors by line number and type

Parameters:

errors - list of iDoc errors (future javadoc addition)

 public String toString()

converts an iDoc errorcode (future javadoc addition) to a string

Returns:

string describing iDoc errorcode (future javadoc addition)

Overrides:

toString in class Object