JavaDoc Generation

Javadoc Generator Settings

Note: I recommend that you use Eclipse’ Javadoc generator (Project > Generate Javadocs), and enable the option for it to automatically create a build.xml ant build file. Then open that build file in EditPad Pro, and customize it to your needs. See the build file in the java_3rdParty project for a prototype example.

%JDK_HOME%\bin\javadoc.exe

Note: JDK_HOME = C:Program FilesJavajdk1.7.0_21

Make sure the Windows Environment Variable PATH contains the directory that contains the javadoc.exe executable file (i.e., %JDK_HOME%bin).

This expands to: C:Program FilesJavajdk1.7.0_21binjavadoc.exe

Note: This won’t expand in the Generate Javadoc dialog box, but you can click Configure, and get the path to expand (%JAVA_HOME%\bin\).

Uncheck, and then re-check “src”. This ensures that every subpackage is checked (just one subpackage is checked by default).

Each option (Private, Packatge, Protected, and Public) is a superset of the options to its right. So select Private, and you get Package, Protected, and Public.

I like this option because it’s nice to see explanations for the private helper methods.

Use this option to generate the default doc style.

Destination: C:\Users\Chris\src\java_3rdParty\doc

Choose this option to generate docs using a different document generation algorithm. For example, you can specify a doclet that generates the docs in PDF form.

See the doclets available for download.

JELDoclet is a doclet that exports the contents of the Javadoc system as XML instead of HTML.

** See if you can create as XSLT with oXygen XML Editor, to generate a custom version of the docs.

Check this option.

I used the title: 3rdParty Java SDK Documentation

I checked all of the options, except @deprecated.

When you set this up properly, it makes your docs more user friendly, I turns all of the data types in your docs into hyperlinks to the external Javadocs for each particular referenced API.

Ideally, you want all of these checked. For the ones that are unchecked (and are labelled “not configured”), search the Internet for the name of the jar. One of the hits will contain the URL for the Javadocs generated for the API. Enter that URL, minus the terminating html file, into the Browse dialog, and click Validate. If it validates successfully, then click OK, and then check the check box beside the archive item.

See: http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#linkoffline

Javadoc relies on a file called package-list to identify the location of Javadocs – beneath a given directory. For some reason, such a file is missing for http://developer.android.com/reference. Therefore the “approach -link http://developer.android.com/reference doesn’t work (you get a warning that the package-list could not be retrieved and no links are generated into your docs). Note that the checkboxes in that 2nd eclipse dialog just assemble -link parameters for you, so that doesn’t really make any difference.

However, Javadoc offers the -linkoffline parameter as a workaround for this situation. It allows you to link to online Javadoc documentation, that you can’t access at the time of generating your own docs. Here’s how it works: While -link takes only one parameter (the URL of the JavaDoc docs you want to link to), -linkoffline takes a second one – the location of the package-list file.

So, to link to the online Android reference documentation, you should not select any checkboxes in the 2nd eclipse dialog, but instead add

-linkoffline http://developer.android.com/reference/ file://C:/opt/android-sdks/docs/reference

in the Extra Javadoc options in the 3rd dialog.

That way you use the package-list of your locally installed Android docs, but the links in your generated Javadoc will actually point to the online version.

I guess this must be where you can apply your custom stylesheet to the docs.

Experiment with this. Try opening the docset in Dreamweaver, and then adding your own style sheet on top of the default one.

Check the Overview checkbox.

Use the path: C:\Users\Chris\src\java_3rdParty\overview.html

As far as I can tell, you can leave this field blank.

-noqualifier java.lang:java.io

This truncates the full path names of the io members, leaving just the class name (like the using statemenmt in C#).

1.7

** When you use this option, the settings are stored in an Ant script named javadoc.xml, that you can resuse to perform the specified Javadoc export without the need to use the wizard.

Existing Ant script can be modified with this wizard (Use Open Javadoc wizard’ from the context menu on the generated Ant script)

Ant Script: C:\Users\Chris\src\java_3rdParty\javadoc.xml

1. In Eclipse, Window > Open View > Other > Ant.
2. Drag & drop the Ant build file from the Project Explorer into this Ant View pane.
3. In the Ant view pane, double-click the target script.

1. In Eclipse, in the Project Explorer, right-click the Ant build file (build.xml or javadoc.xml).
2. Click Open in…
3. Select the XML Editor.

This gives you two views into the Ant script.

First-time Generation of the Docs

1. In Eclipse, click Project > Generate Javadoc. Run Javadoc using the defaults for Destination: “C:\Users\Chris\src\java_3rdParty\doc”.

Customizing the Docs

The Javadoc tool generates output originating from four different types of source files:

Java language source files for classes Package comment files Overview comment files Miscellaneous unprocessed files

Sample Javadoc comment block

/** 3rdParty Java SDK
 * This Java package wraps the 3rdParty web service.
 * @package    PID.java
 * @author     cboorman
 * @copyright  Copyright © 2020, 3rdParty Corporation.
 * @license    http://opensource.org/licenses/mit-license.php The MIT License (MIT).
 * @version    1.0
 * @maintainer Git Administrator
 * @link       https://github.com/3rdParty/java_3rdParty
 * @email      Support <support@3rdParty.com>
 */