javadoc element

The "javadoc" element allows to define a link to a Java class documentation for an API. The attributes of this element are:

• "api": the API, will point to the "JAVASE" API (The Java 8 API) if not present (and the location is not specified), else it will refer to the javadoc API defined in the configuration file. See also location of the javadoc API
• "location": the direct location of the API (alternative to the "api" attribute)
• "path": the path to the class, with package names separated by "." (dot) characters. To separate the name of the internal class from its parent class, use the "$" character, or use the "internalClass" attribute^[1]
  See internal classes for more information
• "altPath": the optional alternate text to present for the path to the class. See Usage of altPath for more information
• "internalClass": the name of the internal class, if the path points to an internal Class^[1]
  See internal classes for more information
• "module": used to specify the module of the class. Note that the module path is required to get the documentation link beginning with Java 11, but are not up to Java 10
• "member": a field or method of the specified class or interface
• "full": there are several possible values for this attribute^[2]
  For packages, the package complete path will always be presented regardless of the value of this attribute
  :
• "false" or "class": (the default) only the class name must be presented in the link associated text
• "true": the complete classpath of the class must be presented in full in the link associated text
• "member": only the member name must be presented. Note that if the path represents a class, it will have the same result as "class"
• "type": the type of the link:
• "class" for a Class (the default value)
• "package" for a package
• "module" for a module
• "checkLink": false to not check the validity of the link even if the configuration property specifies that links should be checked^[3]
  See checking external links

Java module

The "module" attribute is used to specify the module of the class. The module path is required to get the documentation link beginning with Java 11, but are not up to Java 10.

For example all these are valid declarations:

   <javadoc path="java.awt.Button" />
   <javadoc api="JAVASE9" path="java.awt.Button" />
   <javadoc api="JAVASE10" module="java.desktop" path="java.awt.Button" />
   <javadoc api="JAVASE11" module="java.desktop" path="java.awt.Button" />

But this declaration is invalid:

   <javadoc api="JAVASE11" path="java.awt.Button" />

Java.lang classes

It is not necessary to define the full path for many classes in the java.lang package. For example, these declarations are valid:

   This is a link to the <javadoc path="Float" /> class
   This is a link to the <javadoc path="java.awt.Button" member="setLabel(String)" /> method

The list of classes for which the full paht is not necessary is specified here: Example

Internal classes

Internal classes path are separated with a "$" character. It is also possible to use alternatively the internalClass attribute. For example:

   This is a link to <javadoc path="java.awt.geom.Point2D$Float"/>
   This is a link to <javadoc path="java.awt.geom.Point2D$Float" member="getX()"/>
   This is a link to <javadoc path="java.awt.geom.Point2D" internalClass="Double"/>

will have the following result: This is a link to Point2D.Float

This is a link to Point2D.Float.getX()

This is a link to Point2D.Double

Location of the javadoc API

The javadoc API depend on the presence of the "api" and "location" attributes:

• If the "api" attribute exists, the link will point to the javadoc API defined in the configuration file
• Else if the "location" attribute exists, or there is a previously defined setAPIURL element in the current article, the link will point to the URL defined by this attribute
• Else the link will point to the "JAVASE" API (The Java 8 API)

Example:

   <javadoc location="http://docs.oracle.com/javase/8/docs/api/" path="java.awt.Button"/>

Usage of altPath

The "altPath" attribute is an optional alternate text to present for the path to the class. It can be useful if the member is defined for a parent class but you want to show the API for a subclass. It will allow you to present the API on the class you choose and avoid any error emitted because the link is not found in the API.

For example, if you have the following declaration:

   <javadoc path="javax.swing.JButton" member="setLabel(String)"/>

You would have an error, because the setLabel(String) method is defined in the AbstractButton class, and not on its JButton subclass.

But you can declare:

   <javadoc path="javax.swing.AbstractButton" altPath="JButton" member="setLabel(String)"/>

With the following result:
JButton.setLabel(String)

Examples

   This is a link to <javadoc path="java.awt.Button" />
   This is a link to <javadoc path="java.awt.geom.Rectangle2D$Float" />
   This is a complete link to <javadoc path="java.awt.Button" full="true"/>
   This is a link to <javadoc path="java.awt.Button" member="setLabel(java.lang.String)" />
   This is a link to <javadoc path="java.awt.Button" member="setLabel(java.lang.String)" full="member"/>
   This is a link to the <javadoc path="java.awt.geom" type="package" /> package

Result: This is a link to Button

This is a link to Rectangle2D.Float

This is a complete link to java.awt.Button

This is a link to Button.setLabel(String)

This is a link to setLabel(String)

This is a link to geom package