Posted under Java
Permalink
Tags Gotcha, Java, JavaDoc, Tip, Tutorial
Some tips and gotchas on this, as follows :-
1/ the Oracle documentation pages for Javadoc complete with examples etc. may be found here
2/ An example of Javadoc applied to a project may be found in the PropertyTree project in the repository.
3/ JAutodoc is a useful Eclipse plugin. Whilst Eclipse can generate Javadoc comments at source creation time if you tick the box for it, and lets you add them afterwards one by one via ctrl/alt/J etc., using JAutodoc allows creation, addition or replacement of a full set of Javadoc comments to an entire project at any time. It also has a better stab at guessing comments for properties etc. than Eclipse, by parsing words out of the code. Obviously there is still a lot of manual editing to be done, but I found it a useful addition. Note that JAutodoc is available for a project on the package Explorer context menu for a project, but not on the project explorer one.
4/ Package level documentation sits in package.html in the package source directory. As Javadoc is frames based, the following doctype is recommended by Oracle for this file :- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">. Simple html is the order of the day as Javadoc has simple, somewhat retro styling. You can get new style sheets for it to spice it up, but I find the standard ones perfectly readable. Javadoc has its own Stylesheet.css, but I avoided amending this, and deliberately did not add another stylesheet of my own. Therefore, I avoided heavy use of styling, and just borrowed the odd style from the built in stylesheet for my own uses such as table header styling below.
5/ For subheadings in the package doc <h3> and <h4> worked fine.
6/ It was straightforward to add simple tables. Whilst some of the attributes are rather outdated/deprecated in favour of CSS, they are also used elsewhere in the Javadoc for its own tables, so I did not lose sleep over it. I used the TableHeadingColor class from Javadoc’s own stylesheet to give a similar background colour to my own table headers.
<table border="1" cellspacing="1" width="100%">
<tr class="TableHeadingColor">
<th>Column 1 Header</th>
<th>Column 2 Header</th>
</tr>
<tr>
<td>Column 1 data</td>
<td>Column 1 data</td>
</tr>
</table>
7/ Styling code samples is a bit messy with several tags being involved. This post here on StackOverflow discusses some of the issues In the end I used the following examples, generally going with what worked well:-
<blockquote><pre>
PropertyTree propertyTree = new PropertyTree("lan").load("Test.properties");
</pre></blockquote>
or :-
<blockquote><pre>{@code
lan.default.broadcast=10.0.0.255
lan.default.port=7}</pre></blockquote>
The code tag (“{@code …}” was supposed to be the one to use here (particularly when Generics are involved) but was a bit mixed in its usefulness, and I found some variations in the tabbing, and closing braces in the code can be an issue as the code tag also uses this for its own closure. I did not therefore always use it. Interestingly the above StackOverflow post cites that String.java in the JRE just uses <p><blockquote><pre>, so I often followed suit.
8/ Individual code or data identifiers such as class and method names looked good in a fixed font when framed with <code></code>, which seemed to be the preferred way to highlight them. Sometimes I made them links as follows, but I did not do this all the time when there was already a link on the comment, as it was tedious and unnecessary. Links can be added, and you can link to a method, a class or a package (which links to package.html) by just linking to the desired level. The first parameter after {@link is the hyperlink, and the second parameter is the clickable description that appears for the hyperlink. Eclipse does code completion for the tags when you are entering them. The following example links to a property (which is specified after the “#”):-
{@link uk.co.salientsoft.util.propertytree.TagTree#getProperty() TagTree.getProperty()}
9/ One gotcha is that for overriden methods, the Javadoc always comes from the inherited method, and the Javadoc method comments in the subclass are ignored. However, you can add additional comments by using the Javadoc documentation comment syntax (prefixed “/**” i.e. with the extra asterisk on the first line) in the subclass, and these will be added in and not ignored:-
/**
* For the <code>NullIterator</code> this will always return <code>false</code>.
*/
10/ In Eclipse, you can create Javadoc via the Project/Create Javadoc menu bar option (this is not available on the package explorer context menu). There are a number of options when doing so, but these are not all defaulted to your previous settings when you go back next time round. You can therefore create and save an Ant build file for the Javadoc which you can then re-run much more easily. Javadoc.exe needs to be on the path for this – it should be anyway if you have Java SE installed and on the path, and for me I did not have to add it. You can then open the Ant view in Eclipse. In the view pane, right click and select Add Buildfiles… and browse for the Ant build file which you saved at Javadoc creation time. This then stays pinned to the Ant pane and you can double click it any time to recreate your Javadoc with all the saved settings.