Package xbn.jdlcode

Speed up the creation and increase the accuracy of your JavaDoc.

See:
Description

TOP Class Summary

JDCArray	Manage a set of JDClasses.
JDClass	A JDFile that is explicitely defined it the jdlcode doclet class map configuration file.
JDFile	Represents a single JavaDoc (html) file that may or may not contain JavaDoc Link Codes.
PackageType	Defines a package type whose classes are liked to, from your JavaDoc html files.
PTArray	Manage a set of unique PackageTypes.
SplitLinkCode	Example link: <A HREF="~JD~t~EJD~">~JD~t~EJD~</a> --> ../template/Template.html (see package description for details).
UtilJDLCode	Random functions used throughout the xbn.jdlcode package.

TOP Package xbn.jdlcode Description

Speed up the creation and increase the accuracy of your JavaDoc. Every class is assigned an abbreviation by you, existing in a doclet class map (take a look at the actual XBN doclet class map). Logically combining those abbreviations together forms a "JavaDoc Link Code".

JavaDoc Link Codes are backward compatible: They do not interfere with your existing JavaDoc, nor are you restricted from using traditional hard-coded JavaDoc links. A non-interpreted JavaDoc link code is just a broken link. For example: ~JD~utiljdlc~EJD~

Contents:

• ... Example JavaDoc Link Codes: Actual codes, and the relative urls they result in.
• ... Things that don't belong in a JavaDoc Link Code
• ... Other notes you should understand when using JavaDoc Link Codes
• ... Readying Sun's Standard Doclet to use JavaDoc Link Codes

BACK Example JavaDoc Link Codes

Here are some actual JavaDoc Link Codes, and the links they equal:

~JD~over~EJD~	../../overview-summary.html
~JD~over~EJD~#overview_description	../../overview-summary.html#overview_description
~JD~t~EJD~	../template/Template.html
~JD~vwo~EJD~#getAOObject()	../array/VWObject.html#getAOObject()
~JD~jdf#jdf(s,s)~EJD~	JDFile.html#JDFile(java.lang.String, java.lang.String)
~JD~jdc#jdc(s,s,pta)~EJD~	JDClass.html#JDClass(java.lang.String, java.lang.String, xbn.jdlcode.PTArray)
~JD~td#td(s,aosl,aps,s,s,b)~EJD~	../template/TemplateData.html#TemplateData(java.lang.String, xbn.array.AOSLookup, xbn.array.APString, java.lang.String, java.lang.String, boolean)
~JD~jdc#setNameAbbrevOrFQCN(b)~EJD~	JDClass.html#setNameAbbrevOrFQCN(boolean)
~JD~st~EJD~	http://java.sun.com/j2se/1.3/docs/api/java/util/StringTokenizer.html
~JD~st#st(s)~EJD~	http://java.sun.com/j2se/1.3/docs/api/java/util/StringTokenizer.html#StringTokenizer(java.lang.String)

"#overview_description" and "#getString()" are not actually part of a JavaDoc Link Code, but I thought it helpful to put them here.

BACK Other notes

Limitation: It is currently not possible to link to the overview-summary (or any file in the root directory) of an external package.

JavaDoc Link Codes are based upon xbn.template.Template, where each gap is surrounded by ~JD~ and ~EJD~. This is defined by:

new GapConfig(UtilJDLCode.getJDLinkGapTextStart, UtilJDLCode.getJDLinkGapTextEnd)

XBN Java is compiled using JDK 1.3.1, and not and not 1.4. The reason for this is because I cannot yet figure out a problem with the 1.4 Standard Doclet. The problem is that every "@" JavaDoc tag (@param, @exception, @return, ...) is being suppressed--not displaying in the final JavaDoc output.

It's actually pretty simple to upgrade XBN Java to 1.4 (I've done it a few times now), but until I can figure out the JavaDoc problem...

BACK Things that do not belong in a JavaDoc Link Code

The SplitLinkCode constructor has a listing of legal and illegal examples of JavaDoc Link Codes. Take special note of the following three things, which do not belong in a JavaDoc Link Code...

Excepting "doThis(b)", all legal examples can be seen for real in the example section above.

"name" links

Legal: ~JD~over~EJD~#overview_description
Illegal: ~JD~over#overview_description~EJD~

Single-parameter functions

Legal: ~JD~a~EJD~#getString()
Illegal: ~JD~a#getString()~EJD~

This error is not detected by SplitLinkCode. It is detected only by ReportBadJDLinkCodes (and when you actually run javadoc). Note that single parameter constructors are legal.

The opening "#"

When linking to a constructor, or an at-least-one-parameter function within the same class.

Legal: ~JD~doThis(b)~EJD~
Illegal: ~JD~#doThat(b)~EJD~

BACK Readying Sun's Standard Doclet for use with xbn.jdlcode

To get javadoc working with xbn.jdlcode:

1. Get all the source code for Sun's Standard Doclet (version 1.3.1). This is the same version existing in your (1.3.1) JDK's "tools.jar".
2. Move standard.tags.*.java to standard.*.
3. Rename "com.sun.javadoc.doclet.standard.tags" to "xbn_doclet" and all "com.sun.javadoc.doclet.standard" to the same thing: "xbn_doclet".
4. Get rid of all "import xbn_doclet.*;" lines.
5. Compile all files to test_and_docs.
6. Rename Standard.java to XBNDoclet.java, and change all references to "Standard", throughout every file, to "XBNDoclet"
7. Implement all xbn.jdlcode additions existing in HtmlStandardWriter.java, ConfigurationStandard.java and XBNDoclet.java (search for "xbn.doclet code"). There are not that many things to do.
8. In XBNDoclet.java, change the hard-coded directory to the class-map to be valid for your machine.
9. Configure the etcetera/javadoc/doclet_class_map.txt for your Java packages.
10. Compile it and go! I call it in my Jakarta Ant build.xml file (search for <target name="javadoc">)

Aside from JavaDoc Link Codes, I've also added "TOP" links to the package-summary.html pages (see the "Class Summary" table above). These are unrelated to xbn.jdlcode, so don't worry about any changes related to this. They are not surrounded by "xbn.jdlcode code", so you should not get confused.