What is NDoclet?
NDoclet is a doclet that generates MSDN style API documentation from Java source code. NDoclet was inspired by the NDoc documentation tool for .NET and credit goes to the NDoc developers for the stylesheets, scripts and images used by the HTML pages generated by NDoclet.To see what the output generated by NDoclet looks like, look no further. This page as well as the demo API pages available through the navigation tree on the left were all generated using NDoclet.
NDoclet does not implement all the features of the standard doclet but it does add some useful features of its own. For example, NDoclet introduces the @internal tag which can be used to mark public and protected program elements as internal so that they can be excluded from the generated API documentation. NDoclet also introduces the @remarks and @example tags which can be used to move remarks and examples out of the main description of a program element to a less prominent place on the page.
NDoclet is open source software released under version 2 of the GNU General Public License. NDoclet can be downloaded from the NDoclet project page at SourceForge.net. Bug reports, enhancement requests and other feedback are also welcome through SourceForge.
Supported Tags
The following table lists the Javadoc tags supported by NDoclet. NDoclet extensions are in bold.
| Tag | Behaviour |
|---|---|
| @author | As standard doclet. |
| {@code} | As standard doclet. |
| @deprecated | As standard doclet. |
| @example | Marks a text block as an example. @example blocks are gathered in an Examples section at the bottom of the generated documentation page. |
| @exception | As standard doclet. |
| @ifdef name | Causes the marked program element to be excluded from the generated documentation unless the given macro name is defined using the -define command line option. |
| @ifndef name | Causes the marked program element to be included in the generated documentation unless the given macro name is defined using the -define command line option. |
| @internal | Causes the marked program element to be excluded from the generated documentation unless the -internal command line flag is set. |
| {@link} | As standard doclet, except that the link's label is displayed in plain text font to comply with the MSDN document style. |
| {@linkplain} | As standard doclet. |
| {@literal} | As standard doclet. |
| {@name text} | Inserts the value of the macro name defined using the -define command line option. The first occurrence of the '@' symbol in the macro value is replaced by text. A warning message is printed if the named macro is not defined. |
| @param | As standard doclet. |
| @return |
As standard doclet, except that it also establishes a default main description
for the involved method.
For example, if a method int sum(int a, int b) has a @return
block saying "The sum of a and b.", then the default main description is
"Returns the sum of a and b.".
This can prevent unnecessary repetition of comments in the main description
and @return sections of simple methods.
|
| @see | As standard doclet. |
| {@paramref name} | Inserts the name of a constructor or method parameter. Parameter names are set in italic font to comply with the MSDN document style. A warning message is printed if the named parameter does not exist. |
| @remarks | Marks a text block as secondary remarks. @remarks blocks are gathered in a Remarks section at a less prominent location of the generated documentation page than the main description. |
| @since | As standard doclet. |
| @throws | As standard doclet. |
| @version | As standard doclet. |
Running NDoclet
NDoclet can be run as follows:
For example, this HTML page and the HTML pages of the demo packages were generated using a command like this:
javadoc -docletpath NDoclet directory/NDoclet.jar
-doclet ndoclet.NDoclet
-classpath class-path
-sourcepath source-directory
-d output-directory
-doctitle NDoclet
-nopackagetable
-define NDoclet.Version=0.3.2
-overview this-overview-page
-author
-version
-subpackages ndoclet.demo
The following table lists the command line options supported by NDoclet. NDoclet extensions are in bold.
| Command line option | Description |
|---|---|
| -d directory | Output directory |
| -use | Ignored (planned for a later version) |
| -version | Include @version information in generated documentation |
| -author | Include @author information in generated documentation |
| -docfilessubdirs | Ignored (planned for a later version) |
| -splitindex | Ignored (planned for a later version) |
| -windowtitle text | Browser window title |
| -doctitle html-code | Document title |
| -header html-code | Ignored |
| -footer html-code | Ignored |
| -bottom html-code | Bottom text for each page |
| -define name[=value] | Defines a macro with an optional value |
| -internal | Include @internal program elements in generated documentation |
| -link url | Ignored (planned for a later version) |
| -linkoffline url url2 | Ignored (planned for a later version) |
| -excludedocfilessubdir name1:... | Ignored (planned for a later version) |
| -group name p1:p2... | Ignored (planned for a later version) |
| -nodeprecated | Ignored (planned for a later version) |
| -noqualifier name1:name2... | Ignored (planned for a later version) |
| -nosince | Exclude @since information from generated documentation |
| -nodeprecatedlist | Ignored (planned for a later version) |
| -nopackagetable | Exclude package table from overview page |
| -notree | Ignored (planned for a later version) |
| -noindex | Ignored (planned for a later version) |
| -nohelp | Ignored |
| -nonavbar | Ignored |
| -quiet | Show error and warning messages only |
| -serialwarn | Ignored (planned for a later version) |
| -tag name1:locations:header | Ignored (planned for a later version) |
| -taglet class | Ignored (planned for a later version) |
| -taglet taglet-class-path | Ignored (planned for a later version) |
| -charset charset | Ignored (planned for a later version) |
| -helpfile file | Ignored |
| -linksource | Ignored (planned for a later version) |
| -stylesheetfile path | Alternative stylesheet file |
| -docencoding name | Ignored (planned for a later version) |
Version
0.3.2