Todo: Describe the difference between old-style 1.4.x taglets and the new 1.5+ taglets.
Created Wednesday 30/9/1998
The javadoc tag parser contains a link assembly bug which generates a MissingResourceException when the parser encounters text that starts with <a. The parser (incorrectly) interprets any occurance of <a as being the start of a link ref and so starts off a link assembly path. The problem is that not all <a text are link refs. Consider <action for example. The problem with this type of reference is that clearly there is no terminating link ref tag </a and so various required components of the reference cannot be completed with the result being a non-continuable exception.
The solution to the link assembly problem is to either avoid any javadoc references that start with <a. If it is unavoidable, then use either the javadoc literal tag {@literal <} or the html &#lt; constant.
Javadoc tags are marked with the @ character and are enclosed in a java block comment which starts with a double-*. This is similar to the C-like block comment. The following block comment contains several tags:
/**
* This sentence will appear as the description in the table of methods for the class. The rest of the text (along
* with the first sentence) go in the method's descriptive section.
* <p>
* Any html is valid in javadoc. There are also special tags like {@link java.util.List}, which is essentially an href.
* It can also take an optional text value such as {@link java.util.List The List}. The class being linked to must be
* fully qualified unless it is in the same package. To link to a method use {@link java.util.List#add(Object)}. To
* link to a field {@link java.lang.Integer#MAX_VALUE}.
*
* The {@literal} tag is useful when refering to text that is otherwise interpreted as html (see link assembly error in #1).
* An example is the greater- and less-than sign. Typically > is used, but this is less readable. It's also possible to
* use {@literal 1<2} instead.
*
* Block quotes and verbatim text:
* <blockquote><pre>
* "hamburger".substring(4, 8) returns "urge"
* "smiles".substring(1, 5) returns "mile"
* </pre></blockquote>
*
* Param/Return/Exception tags:
* @param beginIndex - The beginning index, inclusive.
* @return The specified substring.
* @exception IndexOutOfBoundsException occurs if beginIndex is less than 0
* @throws FooException if Bar occurs. (Note @throws is different to @exception because @throws is a description of the
* exception listed in the "throws" clause of the signature. The @exception tag does not have to be declared
*
* Version/Author tags
* @version 1.15, 98/09/30* @version 1.15, 98/09/30
* @since 1.2
* @author foo
*
* Cross reference tags. The first @see below is a class reference and the second is a method reference.
* @see FooBar
* @see FooBar#method(String)
*
*/
The Taglet engine used in the javadoc tool is extensible and allows for user-tags to be dynamically. By convention, javadoc tool taglet namespace for user tags should contain a period . in the name, so that there is no confusion with standard taglets and so that future taglet names can be reserved for use as JDK taglets. Example user-tags might be @ff.date, which could print the current date in the generated javadoc.
Each tag supported by the Taglet engine is a java class which implements the Taglet API (defined by com.sun.tools.doclets.Taglet, which is part of the tools.jar. A custom tag is a Taglet implementation which is registered with the javadoc Doclet and Taglet engine. This is done by providing an implementation such as the following register(Map).
Note: Old 1.4.x taglets must be wrapped in a LegacyTaglet instance prior to being added into the taglet map.
public static void register(Map tagletMap)
{
Taglet tag = new MyCustomTaglet("MyTaglet");
tagletMap.put(
tag.getName(),
tag instanceof Taglet ? new com.sun.tools.doclets.internal.toolkit.taglets.LegacyTaglet(tag) : tag
);
}
Todo: Describe the difference between old-style 1.4.x taglets and the new 1.5+ taglets.
The ant tool defines the javadoc task as part of the ant core. The ant task for javadoc generation supports pretty much all the options available to the JDK javadoc binary, of which there are many. Essentially, the javadoc task requires requires a sourcepath (or several sourcepaths) over which it should parse the javadoc from. These are best served by using <sourcepath location=""/> embedded tags. Attributes in the javadoc tag itself are pretty much all optional and mostly control formatting and other non-essential behaviours. All the javadoc task attributes such as src have corresponding embedded tags refs that can be used instead (which are better as they often allow multiple references).
The javadoc task also supports several html output formatting options, which allow the user to provide CDATA array data for setting (e.g.) the header, footer and external javadoc linkrefs. In addition, custom taglets can be registered with the doclet engine. There are two types of tags supported for custom tags. These are the dynamic custom tags, which do not require an existing compiled taglet code. These are specified by the javadoc embedded <tag entries. The other form of custom taglet are the user-taglets implemeting the Taglet API. These tags must be registered with the doclet engine that is running the javadoc tool and this is achieved using the <taglet embedded tags.
The following javadoc task entry shows an example execution of the javadoc tool task, running over 2 separate source code repositories. A header and footer are defined and two types of custom taglets are registered with the doclet engine. The first uses the <tag reference, for which no compiled Taglet code is required and the second uses the <taglet reference, which does require compiled custom Taglet class.
<javadoc
author="true"
destdir="generate/javadoc"
doctitle="New Factory"
packagenames="com.fluencyfinancial.newFactory.*"
stylesheetfile="src/WEB-INF/stylesheet-fluency.css"
version="true"
charset="UTF-8"
locale="en_AU"
source="1.5"
linksource="yes"
windowtitle="New Factory API"
breakiterator="yes"
use="yes"
access="private"
maxmemory="512M" >
<sourcepath location="newFactory/src"/>
<sourcepath location="junit/src"/>
<classpath refid="runtime-path"/> <!-- A refid to a classpath, this should include compiled code+libs -->
<header>
<![CDATA[<small>TWiki <a href="http://bumerang/twiki/bin/view/Camel">Camel</a> Web</small>]]>
</header>
<tag name="date" description="Date of implementation:" enabled="true" scope="all"/> <!-- Dynamic custom tag -->
<taglet name="com.fluencyfinancial.antExtensions.taglet.ToDoTaglet"> <!-- Must be a compiled class of the Taglet API -->
<path refid="runtime-path"/>
</taglet>
<bottom>
<![CDATA[<small><table width="100%"><tr><td>Copyright © 2003-2008 Fluency Financial LLC</td><td align="right">Generated ${TODAY}</td></tr></table></small>]]>
</bottom>
<group packages="com.fluencyfinancial.frontEnd*" title="GUI"/> <-- Group 1: Packages in the "frontEnd" -->
<group packages="com.fluencyfinancial.${moduleName}.security*" title="Security and JAAS"/> <!-- Group 2: Security packages -->
<link href="http://bumerang/javadoc/j2se/docs/api/"/> <!-- If available, external javadoc links will point here. Classic case is the Object ref -->
<link href="http://java.sun.com/j2se/${javadoc.j2see.link.version}/docs/api/"/> <!-- Fallback J2SE, if cached one (above) not available -->
<link href="http://bumerang/javadoc/log4j/current-log4j/api"/> <!-- Any javadoc refs to log4j will point to here (if available) -->
Stuart Moorfoot © 30 September 1998 foo@bund.com.au