JavaDocs, Quick and Dirty

I mentioned JavaDoc tags to someone in class, and we didn’t have time to go into details. Since it’s something that’s likely to be useful to us all later on, here’s the low-down:

“JavaDoc” encompasses a built in API documentation generator and the stuff you write in your code to flesh out that documentation.

Oracle has a kind of dense, not helpful, white paper on javadoc comments at “How to Write Doc Comments for the Javadoc Tool”

So, here are the essentials:

You write javadoc comments like:

/** the below variable is a generic integer variable. 
Anything after the period will show up in the extended description.
*/
private int classGeneric;

/** your line spacing does not matter */
private int classInt;

/**
This is a general description of the method that follows. Again,
anything after the period will show up in the extended description.

@param t1 this line spacing does matter – @param is a tag that says
“I’m going to talk about my parameter now”. parameter tags go just
above the return tag.

@return This line spacing matters – @return is a tag that says “I’m
telling you what my return really means.” the return tag goes at the end.
*/
public int doc(int t1) { return t1; }

Two things to draw attention to : the JavaDoc comments start with /** and end with */. They are a special type of multi-line comment. And the JavaDoc comment goes directly above the method or variable that you’re describing.

Now that you’ve got the javadoc comments seeded throughout your source code, how do you get that into an API? Well, jGrasp won’t help with that.

For those on Windows, I’ve got a batch file for you. For those of you on Linux boxes, I expect you understand how to convert this into a shell script.

The batch file contents (leave a comment if you need help with this):

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

@ECHO OFF
ECHO %CD%
PAUSE
REM ### this file needs to be in the same directory as your source code
REM ### to switch between standard javadoc and internal-use, 
REM ### comment out one of the two "javadoc" lines below.
REM javadoc -d "%CD%javadoc" *.java
javadoc -author -version -private -d "%CD%javadoc" *.java
ECHO FINISHED MAKING JAVADOCS

REM below opens the javadoc index page after generation
.javadocindex.html
PAUSE
REM added in because windows 8 was ignorning the pause above
ECHO “THANK YOU!”
PAUSE

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~