United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4421066 : Doclet API: Generics versus javadoc and the doclet API

Details
Type:
Bug
Submit Date:
2001-03-02
Status:
Resolved
Updated Date:
2003-08-30
Project Name:
JDK
Resolved Date:
2003-08-30
Component:
tools
OS:
solaris_7
Sub-Component:
javadoc(tool)
CPU:
generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
5.0
Fixed Versions:
5.0 (tiger)

Related Reports
Relates:
JDK-4965490 - Inline tag should end at the matching closing brace.
Relates:
JDK-4909767 - Add Doclet.languageVersion method.
Relates:
JDK-4421040 - JPDA: Add Generics support

Sub Tasks

Description
        Note that because javadoc has an exclusively source level 
        perspective, javadoc will be broken if generic support does
        not roll out with generics.

        Impact on Doclet API
                Two new sub-interfaces of Type will need to be added.
                Their exactly structure will need to be carefully
                considered so that existing doclets "fail" as gently
                as possible.  Several other methods will need to be
                added to MethodDoc, ClassDoc, Type, ...
                See discussion of class definition vs class use, at 
                the bottom.

        Impact on Doclet API implementation (aka javadoc tool)
                This requires that:
                * we complete (or re-implement) the Doclet API 
                  implementation on the new compiler.
                * we extend it with the new API functionality.

        Impact on Standard Doclet
                This change will have some impact on just about every 
                corner of the Standard Doclet.

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
tiger

FIXED IN:
tiger

INTEGRATED IN:
tiger
tiger-b18
2004-06-14 
EVALUATION

Yes, this is absolutely true.

gilad.bracha@eng 2001-03-02

I don't think the impact is as earth-shattering as this description implies.

neal.gafter@Eng 2001-03-19

Note there is a difficult issue in generifying the documents: what syntax will
be used to indicate generic parameters?  If we use the obvious source-level
syntax in the documents

	<I>

that will look like an HTML tag and turn everything italic.
On the other hand, if we use the obvious HTML syntax

	&lt;I&gt;

then our users will wail and moan.  Perhaps we need to invent a compromise
just for javadoc - such as an embedded tag

	@tparam(I)

Then Map<K,Map.Entry<K,V>> will be written

	Map@tparam(K,Map.Entry@tparam(K,V))

Alternately, perhaps we should stop trying to directly support HTML.

###@###.### 2003-03-23
2004-06-11 
PUBLIC COMMENTS

...
2004-06-10


Hardware and Software, Engineered to Work Together