Javafxdoc Tags Part Deux

I wanted a list of all possible javafxdoc tags that are available when documenting JavaFX classes. Since the documentation that comes with the SDK is missing some information, I had to go digging through the source code for the tool itself, along with the code for the standard doclet and the XSL files.

So, compiled for you below, is a list of all tags that are specifically mentioned in the chain of components that make up the javafxdoc tool (as of SDK 1.2.3):

Tag	Function
@advanced	Adds “advanced” to the CSS class for the method documentation.
@author	Not used when transforming to HTML.
@defaultvalue	Documents the default value for a variable.
@deprecated	Not used when transforming to HTML.
@example	Formats some example code, then attempts to show the results in the documentation for the class.
{@inheritDoc}	Copies method documentation from the nearest parent class in the inheritance tree.
{@link}	Inserts an inline link to a class method or variable. Uses the form package.class#member label.
@needsreview	Adds “This comment needs review.” to documentation for classes, methods, and variables.
@param	Documents the parameters for a method.
@profile	Notes the profile of the class: common, desktop, or mobile.
@return	Documents the return value for a method.
@since	Not used when transforming to HTML.
@see	Adds a “See Also” note, but can only take the form of package.class#member label. You can’t use URLs or plain text.
@throws	Documents exceptions for a method.
@treatasprivate	This lets you hide the documentation for classes or variables. Even if you set the -private flag on javafxdoc, classes or variables with this tag will not appear in the generated HTML. Note that a class still has a file generated for it, but it is just not linked into the index pages. Documentation for variables is not generated at all.
@version	Not used when transforming to HTML.

Documentation for these tags are part of the site documentation for the maven-javafxdoc-plugin 1.0 release.

maven-javafxdoc-plugin v0.9 released

Version 0.9 of the maven-javafxdoc-plugin has just been released at the project site. Check out the release notes to see a detailed list of the changes in this version. Note that the nodeprecated, nosince, and author options are not supported since the standard doclet does not do anything with them.

Testing this plugin has reinforced my belief that unit testing is not enough. You have to do integration testing. I found this out the hard way when I went to use the 0.7 plugin in a Maven project to generate the site documentation. It didn’t work. I had forgotten to implement the MavenReport interface in the mojo! Perhaps my unit testing needs revised…

Give it a whirl and log any issues to the tracking system.

maven-javafxdoc-plugin v0.7

I needed to create a web site for the SplitNode project, and stumbled into the Maven site:site goal. This was exactly what I needed – a way to generate a web site for the project with a minimal amount of effort on my part. Everything was going great until I wanted to generate the documentation for the JavaFX files. There was not a plugin for calling javafxdoc.

Using the maven-javadoc-plugin as a template, I have created the maven-javafxdoc-plugin. At this time, version 0.7 has been released, and is available from the project site.

The following table lists the standard options mapped to the plugin configuration:

Javafxdoc Option	Maven Javafxdoc Plugin Option
-overview	Not supported (standard doclet does not generate this information)
-public	show
-protected	show
-package	show
-private	show
-help	Not supported (gives the usage information for javafxdoc then quits)
-doclet	doclet
-docletpath	docletPath
-sourcepath	sourcePath
-classpath	Built from project information
-exclude	excludePackageNames
-subpackages	subpackages
-breakiterator	breakiterator
-bootclasspath	bootclasspath
-source	source
-extdirs	extdirs
-verbose	verbose
-locale	locale
-encoding	encoding
-quiet	quiet
-J<flag>	additionalJOptions

The following standard doclet options are also supported:

Doclet Option	Maven Javafxdoc Plugin Option
-o	outputFile
-version	Not supported (gives the Javafxdoc version and quits, instead of generating @version information)
-author	author
-nosince	nosince
-nodeprecated	nodeprecated
-nohtml	nohtml
-xsltfile	Not supported (yet)
-mastercss	Not supported (yet)
-extracss	Not supported (yet)
-extrajs	Not supported (yet)
-extrajs2	Not supported (yet)
-xsl:	Not supported (yet)
-d	outputDirectory
-i	Not supported (yet)

I found these options by running the tool at the command line and looking at the source in the JavaFX SDK. The documentation page for javafxdoc in the JavaFX 1.2.3 distribution is quite out of date. It lists options that do not work (yet?) while omitting some options that do.

The upcoming 0.9 release will focus on finishing support for the standard doclet options and covering as much code as possible in the unit tests. Once 1.0 has been released, I will add new goals such as javafxdoc:jar.

Feel free to download the jar and try it out. Feedback is welcome and you can log issues at the project tracker page.