Changes to Standard Doclet for Javadoc 1.2

Javadoc 1.2 has a "standard doclet" that determines what the default generated HTML contains and looks like. The following sections describe the content and format changes between Javadoc 1.1 and 1.2 that are implemented in this standard doclet. Further details are given in the "Detailed Changes" section that follows.

CHANGES FOR WRITING DOC COMMENTS

Javadoc 1.2 has the following new requirements and features you can use when writing documentation comments:

SUMMARY OF CHANGES

This is the summary of changes to the content and format in the Javadoc Standard Doclet from Javadoc 1.1 to 1.2.

CONTENT

Provides more API information

Customizable title, header and footer

FORMAT

Images and auxiliary files

Improved navigation

Index improvements

Hierarchical Destination File Structure

Other Doclets

Future Enhancements After JDK 1.2


Detailed Changes

These are the detailed changes to the content and format in the Javadoc Standard Doclet from Javadoc 1.1 to 1.2. Features denoted as "Done" are done in 1.2 Beta 3.

CONTENT - PROVIDES MORE API INFORMATION

Add to source tree one file per package, named "package.html", dedicated to doc comments. The first sentence of each package description is the summary. Javadoc picks up everything between <body> and </body> and add it to the package summary page "package-page.html" (which also contains a table of its classes and interfaces). Javadoc copies the first sentence of this to the overview page "overview.html". Therefore, you should not put a title or any other text between <body> and the first sentence.

Outline for package-level comments:

  • Introduction
  • Package Specification
  • Related Documentation

For more information, see Package Level Comments.
(Done)

Javadoc 1.1 has no mechanism for including comments specific to a particular package.
NOTE - The above feature requires writers to follow a new Javadoc rule: The first sentence of each package description should be a summary statement.

Add a single system-level document "overview.html" for the set of packages. This file is specified with the -overview option on the command line and its contents is inserted into packages.html. This is a good place for comments that apply to all packages. For example, the API docs assume that "NullPointerException is thrown wherever null is passed in, except as noted."
(Done)
Javadoc 1.1 has no mechanism for including comments that apply to all packages.

Javadoc picks up the first sentence one-line summary for each package from package.html and puts it in packages.html. This provides a brief summary of each packages in the list of all packages.
(Done)
Javadoc 1.1 has no such summary list.

Pick up the first sentence of each class description and include it in the class summary at package-<class>.html This provides a brief summary of all classes for a given package.
(Done)
Javadoc 1.1 has no such summary list.
NOTE - The above feature requires writers to follow a new Javadoc rule: The first sentence of each class description should be a summary statement.

Add inherited API to method and field summaries on class and interface pages.
(Done)
In Javadoc 1.1, the inherited members for a given class do not appear on the class page, necessitating following links to discover them.

Include return type and keywords "static", "protected" and "abstract" in the signature in the method summary, since they are needed by someone calling a method. Do not include public, transient, volatile, or final; those appear in the detail section further down the page. Include data type of fields.
(Done)
In Javadoc 1.1, method summaries don't indicate the return type. Field summaries don't indicate the field type.

Add "Specified by" (or "Implements") for members that implement an interface.
(Done)
In Javadoc 1.1, members of a class that implement an interface make no such mention.

Add the list of subclasses below the small class tree at the top of the class page. Yet to determine whether this should be direct subclasses only or all subclasses. Add the implementing classes for interface pages.
(Done for the direct case)
Javadoc 1.1 does not list subclasses on a class page.

Copy the description automatically from the method in an interface to its implementing subclass only when the implementing method contains no text. Include a boilerplate statement that says that the text is copied from the interface. The reason for doing this, is that when implementing an interface, the method descriptions are often identical for both the interface and the class. Copying the descriptions manually seems like needless work that is difficult to maintain.
(Not in Beta3. Planned for Beta4.)
Javadoc 1.1 does not copy method descriptions from an interface.

Add a tree view for each package. When you are viewing a package or class, the "Tree" link goes to that view, which then has a link to the tree for all packages.
(Done)
Javadoc 1.1 has no tree view (class hierarchy) of single packages. The only tree view is of all packages, which, for the JDK, is overwhelming.

Add -linkall option to include links. Default is to not link to rest of docs.
When someone re-generates docs for a small branch of the source code, they should have the choice whether or not to link to the rest of the docs in that source tree. This allows their docs to either be standalone (no extra links) or fit into the full doc set (with extra links).
(Done)
Javadoc 1.1 makes no links to documentation outside what is being generated.

Submit bugs against default constructors that should not be documented by Javadoc. We should either deprecate them or remove them as bugs.
(Does not affect Javadoc)
Javadoc includes all default constructors, whether or not an application developer would ever call them. When it documents default constructors, it leaves their descriptions blank.

Add a deprecated summary page listing all deprecated API. (Eventually we will add links to the replacement API.)
(Done)
Javadoc 1.1 does not generate a list of deprecated API.

Mark classes that are deprecated.
(Not in Beta3. Planned for Beta4)
In Javadoc 1.1, deprecated classes are not marked as such in the class list for a given package.

Remove "synchronized" and "native" from signatures. Javadoc generatees an API specification, and these keywords do not belong in the signatures of a specification, because they are implementation-specific. The keyword "native" does not need to be documented. The keyword "synchronized" indicates thread-safe behavior that should instead be described in the method descriptions. A thread-safe method itself might not use the "synchronized" keyword but might call private methods that are.
(Done)
Javadoc 1.1 includes the keywords "synchronized" and "native".

CONTENT - CUSTOMIZABLE TITLE/HEADER/FOOTER

Add the -title option to include a title to first page "packages.html". Example title: "Java Platform 1.2 Core API".
(Done)
Javadoc 1.1 has no formal way to add a title to the generated document.

Add -header, -footer, -bottom options for header/footer/bottom on every page. This enables you to put the version number on every page so that when you print out a page, you have a record of the version it came from. The "bottom" feature lets you add a copyright notice or feedback email link at the bottom of each page.
(Done)
In Javadoc 1.1, the Java version number by default does not appear on any page.

CONTENT - TO DO IN A RELEASE AFTER JDK 1.2

Devise some tag to use the @see mechanism inside descriptions. This feature is also called "in-line @see tags". This would solve two problems:
1) Descriptions of deprecated API currently do not have links to the API that replaces it. It would be useful to say: "This method is replaced by the <<paint>> method."
2) In any description, it would be useful to be able to generate a link for an API name. For example: "This method accepts a <<String>> object."
(Not done in Beta3 - do in a release after JDK 1.2)
Javadoc 1.1 does not have this in-line @see capability.

CONTENT - WON'T DO

For internal development, having direct links from each Javadoc-generated class page to its source code would be handy.
(Won't do)

FORMAT - IMAGES AND AUXILIARY FILES

Elminate any required GIF images. Replace the GIF bullets with horizontal rules. Replace the graphic headings (e.g., "Methods", "Fields") with text inside colored table cells.
(Done)
Javadoc 1.1 requires GIF images for bullets and headers. These are not necessary, they slow down the display, and they need to be manually copied to the destination.

Add directory "doc-files" (one per package). Javadoc copies those directories and their contents to the destination. This directory can contain arbitrary files referenced by doc comments. Examples: images, HTML files, text files, example source code, HTML tables shared by more than one class.
(Not in Beta3. Planned for Beta4.)
In Javadoc 1.1, running Javadoc generates files with broken links because images are not copied to the destination. (In the JDK, these images are currently mostly screen shots of AWT and Swing components.)

FORMAT - IMPROVED NAVIGATION

Add frames for package, class and member. (For no frames, start at "packages.html". For frames, start at "frame.html")
(The frames for package and class are done for Beta3. The frame for members may be in Beta4.)
Javadoc 1.1 has no easy way to access any package, class or member. It requires users to backtrace.

Add "All classes" link to top of package list (upper left frame). When user clicks this, it should display list of all classes in alphabetic order in lower left-hand frame.
(Not in Beta3. Planned for Beta4.)
Javadoc 1.1 has no easy way to access any class, regardless of the package it is in. It requires users to go to "Class Hierarchy". It would be nice to have a list of just classes and interfaces.

Develop a single navigation bar that works in all screens. Dim out the unused items.
(Done)
In Javadoc 1.1, the standard navigation bar along the top changes dramatically from page to page. There are three different navigation bars: all packages (2 items), a package (3 items), and a class (6 items).

Add another navigation bar to jump to each subsection.
Summary: Inner | Field | Constr | Method   &nbps;   Detail: Field | Constr | Method
(Not Done in Beta3. Planned for Beta4.)
Javadoc 1.1 requires you to scroll past the class description to get to the member summaries and detail.

Rename the "API Users Guide" link to "Help". Modify Javadoc to copy the proper file, and add an option to omit the link if desired.
(The link is renamed in Beta3. The file will be copied in Beta4.)
Javadoc 1.1 has a link in packages.html called "API Users Guide". The file it points to is not automatically copied to the destination directory.

FORMAT - WEB PAGES

Change the summaries to tables with borders and cell background color. This better distinguishes between summary and detail portions of class files.
(Done)
In Javadoc 1.1, both the summary and detail portions both look quite similar, it's not obvious when scrolling down the page which section you are in.

Keep "Index" as the name of the alphabetized list of API at the end of the document. Rename top portion of each package page from "Package Index" to "Package Summary", likewise for top portion of each class page rename "Method Index" to "Method Summary", "Constructor Index" to "Constructor Summary", and "Field Index" to "Field Summary".
(Done)
In Javadoc 1.1, the word "index" is used to identify both summaries at the top of class pages, and the alphabetic book-type list containing all the API. This is needlessly confusing.

FORMAT - INDEX IMPROVEMENTS

Add -breakindex option to break the index into a separate file for each letter of alphabet.
(Done)
In Javadoc 1.1, the index is a gigantic 1.4MB file for JDK; takes forever to load over Internet.

Add classes and interfaces to the index.
(Done)
In Javadoc 1.1, the index lists only constructors and members, not classes or interfaces.

Internationalize the index, to enable any Unicode characters.
(Done)
In Javadoc 1.1, the index handles only the alphabet A-Z. (Actually, only A-Y.)

FORMAT - HIERARCHICAL DESTINATION FILE STRUCTURE

Add hierarchical destination directories that follows the source code tree of one directory per subpackage. Flat structure will no longer be supported. This has the effect of reducing the number of files in a directory (>1400 files for JDK).Side effect is to reduce length of filenames, since package names will be directory names rather than part of the filename. This will make it easier for third parties to generate 31-character names that retain some meaning. For example, java.awt.Butotn.html will now be \java\awt\Button.html
(Not done in Beta3. Planned for Beta4.)
Javadoc 1.1 uses a flat structure, where all HTML files sit in a single directory.

FORMAT - OTHER DOCLETS

Maintain Javadoc 1.1 format in its own doclet. This keeps the old look and flat directory structure but with some of the new bug fixes. To access this, use the "-1.1" javadoc option (known as "-X1.1" in Beta 2).
(Done)
The Javadoc 1.1 format is important for those who has built parsers that operate on and rely on that HTML output.

Implement a MIF doclet. This will add the ability to generate MIF output, for importing into FrameMaker.
(Plan to do and release separately from JDK.)
Javadoc 1.1 has no MIF capability (Javadoc 1.0.2 does).

FUTURE ENHANCEMENTS - TO DO IN A RELEASE AFTER JDK 1.2

Allow for cross-linking of Javadoc-generated documents. There are different strategies for this. We might have a simple means for simply adding links from one document to another that requires only the HTML documents. And a more complete solution that might require merging some intermediate format of both documents, as given below.
(Not done - planned for a release after JDK 1.2)
Javadoc 1.1 does not allow a developer to cross-link their own Javadoc-generated API docs (or those of third-party developers) with the API docs we distribute.

Allow for incremental builds contributing to a single Javadoc-generated document. Would be useful to save the intermediate format from each Javadoc run and allow merging of those intermediate formats into a complete document, with fully correct index, tree, class hierarchy, subclasses list, etc.
(Not done - planned for a release after JDK 1.2)
Javadoc 1.1 does not allow incremental building of documentation.