-
CSR
-
Resolution: Approved
-
P3
-
None
-
source
-
minimal
-
This is a new feature, providing a new tag for use in documentation comments. Existing historical use in JDK of a private internal tag with the same name has already been eliminated.
-
Java API, add/remove/modify command line option, File or wire format
-
JDK
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
- csr of
-
JDK-6251738 Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec)
-
- Resolved
-
- links to