United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4282805 : stddoclet API: Add tag listener interface for custom tags

Details
Type:
Enhancement
Submit Date:
1999-10-20
Status:
Resolved
Updated Date:
2014-05-05
Project Name:
JDK
Resolved Date:
2001-07-13
Component:
tools
OS:
solaris_2.5,solaris_2.6,generic
Sub-Component:
javadoc(tool)
CPU:
sparc,generic
Priority:
P5
Resolution:
Fixed
Affected Versions:
1.2.0,1.3.0,1.4.0
Fixed Versions:
1.4.0 (beta2)

Related Reports
Duplicate:
Duplicate:
Duplicate:
Relates:
Relates:
Relates:

Sub Tasks

Description
Add a listener interface to make it simple for developers to add their
own custom Javadoc tags.  A developer would only have to write a listener
class that tells the doclet how to deal with the new tag.
This would enable the custom tag code to continue working with new versions of
javadoc.

                                    

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
merlin-beta2

FIXED IN:
merlin-beta2

INTEGRATED IN:
merlin-beta2


                                     
2004-06-14
EVALUATION

At the '99 JavaOne Javadoc Bird of a Feather, I held a survey of those
developers present what features they wanted (without offering any
features to them).  This was suggested by Steve Lewis, who
has written Warnlet/Codelet doclets.  After the group came up with their 
list of features, I asked them to vote.  This was voted the MOST HIGHLY
REQUESTED feature -- 56% of them wanted it.
Should be passed by TRC, since at one point they did not want the 
tags to be extensible -- they considered the tags part of the language.
doug.kramer@Eng 1999

As the RFE is entered it is not clear what is being requested.
As a feature of the doclet API it doesn't make sense since timing
is unspecified.  As a flag to the standard doclet, I am dubious 
the someone would write this doclet code and no other code.  Finally
as a architectural change in the standard doclet that makes customization
easier, it is probably a good idea, but certainly not a priority.
rfield@Eng 1999-10-20

The doclet API doesn't do anything special with the tags. A doclet
can process whatever set of tags it wants. It seems that this is something
that would have to be done in the context of the standard doclet,
presumably by providing an API for clients to extend it, or by reorganizing
it to make it much easier to extend it by inheritance.

neal.gafter@Eng 2001-03-06

Am reassigning to Jamie.  I think we should pass this by the TRC.
doug.kramer@Eng 2001-03-06

Related RFEs:  

4359470 javadoc tool: Modify Comment.java for easy writing of custom tags
4039014 stddoclet: Tag listener-Flag misspelled tags while printing custom tags
4170018 stddoclet: Want ability to create simple custom tags without writing a
        doclet  (suggests @tag <newtag> <description>)
doug.kramer@Eng 2001-06-15

PROPOSAL #1

Perhaps a command line option such as

  -customtag precondition "Pre-Condition"

that would honor @precondition as a tag and print out "Pre-Condition"
heading in the text.  


PROPOSAL #2

Create a custom.tags file that lists custom tags and corresponding
text:

@pre	"Pre-Conditions"
@post	"Post-Conditions"

=====

This RFE has been implemented.  Location of fix:

Configuration.java
ConfigurationStandard.java
standard.properties
HtmlStandardWriter.java
AbstractSubWriter.java
ConstructorSubWriter.java
Taglet.java
CustomTagFactory.java
SimpleTaglet.java

jamie.ho@Eng 2001-06-26
                                     
2001-06-26
PUBLIC COMMENTS

Will investigate and fix for 1.4 beta.
jamie.ho@Eng 2001-05-1

This RFE has been implemented.  A Taglet abstract class has been added to com.sun.tools.doclets.  Users may write classes that extend Taglet to add their own custom tags to the standard doclet.  Taglets are passed to the standard doclet using -taglet and -tagletpath.  If the user only wants to add a simple single argument tag to the output with no special formatting, they may do so with the new -tag argument.

jamie.ho@Eng 2001-06-26

Support for custom inline tags has been added.
jamie.ho@Eng 2001-06-28
                                     
2001-06-26



Hardware and Software, Engineered to Work Together