hoglet - JavaDoc Handler

JavaDoc Handler

The javadoc handler will produce links to javadoc documentation files. It uses a combination of the content of the tag and options to produce the link. In all cases, if provided, the content of the tag will become the content of the link.

The handler is implemented by the JavadocHandler class and initialized via the XML Configured Processor.

To make referencing easier the javadoc handler allows the class name itself to be used and allows "shortcut" names to be used to reference the website where the documentation is hosted.

For example:

[javadoc jdom,org.jdom.Element/]

becomes:

org.jdom.Element

The handler understands the difference between internal (to a site) links and external links. If no content is given for the link then the options are used for the url and link content instead.

Handler Options

The handler supports the following options:

Name	Optional	Type	Description
1	No	Any value	Should be one of the "short names" that map to a url.
2	Yes	Any value	If not provided then the content of the tag is used. Should be either a class name (use "." rather than "/" but not required), or a class name and a method/identifier appended and separated by # (as you would for a normal javadoc link. Note: if you are using the standard delimiters then you must ensure that the , value is escaped otherwise the handler will be passed multiple anonymous options (one per argument in a method call) and strange results will occur.
lastid	Yes	Any value	If present then the handler will use the "last id" of the javadoc reference. For example if you have provided class name: org.hoglet.Processor then hoglet will use Processor as the link content. If you have provided: org.hoglet.Processor#process(java.io.Reader, org.hoglet.ParserCharset) then hoglet will use: process(java.io.Reader, org.hoglet.ParserCharset) as the link content instead.

XML Initialization

The init element should contain a templates element that should then contain an internalWrapper element and an externalWrapper element. The internalWrapper template will be used for links internal to the site (those that have a url that does not start with http://). The externalWrapper template will be used for links external to the site, i.e. those that start with http://.

The init element can also contain one or more link elements. Each link element should contain an id attribute which provides the "short name" for the javadoc reference and a url attribute which should provide the url to where the javadoc documentation is being hosted.

Example:

<init>
      <link id="josql"
        url="http://josql.sourceforge.net/javadocs/" />
      <link id="hoglet"
        url="javadocs/" />
      <link id="java"
        url="http://java.sun.com/j2se/1.5.0/docs/api/" />
      <link id="jdom"
        url="http://www.jdom.org/docs/apidocs/" />
      <templates>
        <externalWrapper><[CDATA[<span><a title="External site, opens in new window" target="_blank" href="[[VALUE]]" [[OPTIONS]] Class="javadoc-link"><img alt="External site, opens in new window" src="imgs/extlink.gif" border="0" />&#160;[[NAME]]</a></span>]]></externalWrapper>
        <internalWrapper><[CDATA[<a href="[[VALUE]]" [[OPTIONS]] Class="javadoc-link">[[NAME]]</a>]]></internalWrapper>
      </templates>
    </init>

Example Usage

A link to class: org.hoglet.Processor:
```
[javadoc hoglet,org.hoglet.Processor/]
```
Would produce: org.hoglet.Processor
A link to method: JavadocHandler.isAutoExpandContent ():
```
[javadoc hoglet,org.hoglet.handlers.core.JavadocHandler#isAutoExpandContent()/]
```
Would produce: org.hoglet.handlers.core.JavadocHandler.isAutoExpandContent()
A link to a JDOM Element, but providing some content:
```
[javadoc jdom,org.jdom.Element]JDOM element[javadoc]
```
Would produce: JDOM element