Summary

Introduce a tag and related command-line options so that the Standard Doclet can generate a list of external specifications referred to from the main API documentation.

Problem

A specification rarely exists in isolation and often depends on external specifications. While the Standard Doclet has always supported the ability to refer to other API specifications also generated by the Standard Doclet, it currently falls back on plain old HTML <a href="URL">...</a> to refer to other kinds of external specifications. These links are not uniquely distinguished in any way, and so cannot easily be subject to additional analysis and processing.

One aspect of using HTML links is that there may be references into different pages of a multi-page specification, and so it would be useful to specify the "root page" of such a specification.

Another aspect of using HTML links is that the linked text may not directly correspond to the formal title of the document. Again, this is particularly true in the case of multi-page specifications, and so it would be useful to specify the preferred title of any external specification.

External specifications may be referred to by absolute URLs, or by using relative URLs to nearby documentation. For the JavaSE/JDK API documentation, we provide "narrative" (non-API) specifications nearby in a sibling specs directory. These are referred to in the documentation comments with the following clumsy construction: <a href="{@docRoot}/../specs/REST-OF-PATH">...</a>. It would be better to streamline this construction.

Solution

Introduce a new block tag @spec to identify the URL and title of each external specification. In this tag, absolute URLs will be taken as-is. Relative URLs will be evaluated relative to a URL that can be specified on the command line, which defaults to the expansion of {@docRoot}/../specs/

For example,

/**
 * Description ...
 *
 * @spec https://www.ietf.org/rfc/rfc0959.html File Transfer Protocol
 * @spec javadoc/doc-comment-spec.html
 *       Documentation Comment Specification for the Standard Doclet
 */

The first example identifies a reference to IETF RFC 959. The second example uses a relative URI to identify a reference to a JavaDoc specification found in the associated specs directory found in JDK documentation beside the main api directory.

Specification

There are various parts to the specification:

• a new block tag,
• a new interface to represent instances of the tag (with corresponding updates to visitor classes), and
• a new command-line option to be used when analysing tags and generating pages.

Instances of the tag in a documentation comment are collected and displayed in a section headed External Specifications, in a manner similar to @see tags being collected and displayed in a section headed See Also.

The URL and title are added to a new page that contains a summary of all external specifications, with references back to the point of use. The title is added to the static index and interactive search index, again with links back to the point of use.

When generating the summary page, the mapping between URLs and titles must be 1-1: it is an error if different titles are specified for the same URL, or if different URLs are specified to have the same title.

New @spec Tag

@spec URL title

Identifies an external specification in terms of its URL and title. The URL may be absolute or relative. Relative URLs will be evaluated against a "base URL".

All tags specifying the same URL should provide the same corresponding title; conversely, tags with different URLs should have different titles.

New Interface com.sun.source.doctree.SpecTree

A new interface is added in the Compiler Tree API to represent the new @spec tag, along with corresponding updates to the visitor classes and DocTree.Kind enum. These are specified in the attached file specdiff01.zip, or here: http://cr.openjdk.java.net/~jjg/6251738/specdiff.01/overview-summary.html.

New Command-Line Option

--spec-base-url url

Specifies the base URL for relative URLs in @spec tags, to be used when generating links to any external specifications. It can either be an absolute URL, or a relative URL, in which case it is evaluated relative to the base directory of the generated output files. The default value is equivalent to {@docRoot}/../specs.

For example,

Here are the changes to the javadoc command-line help:

>     --spec-base-url 
>                   Specify a base URL for relative URIs in @spec tags