Java Solaris Communities Sun Store Join SDN My Profile Why Join?
 
Bug Database
Bug Detail
Quick Lists
Top 25 Bugs
Top 25 RFE's
Recently Closed Bugs
Printable Page Printable Page


Bug Database
Bug ID: 4282805
Votes 2
Synopsis stddoclet API: Add tag listener interface for custom tags
Category doclet:tbd
Reported Against 1.2 , 1.3 , 1.2fcs , 1.2beta2 , 1.2beta3 , merlin-beta
Release Fixed 1.4(merlin-beta2)
State 10-Fix Delivered, request for enhancement
Priority: 5-Very Low
Related Bugs 4170018 , 4214766 , 4359470 , 4395777 , 4465111 , 4102647
Submit Date 20-OCT-1999
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.
Work Around
N/A
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.
  xxxxx@xxxxx   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.
  xxxxx@xxxxx   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.

  xxxxx@xxxxx   2001-03-06

Am reassigning to Jamie.  I think we should pass this by the TRC.
  xxxxx@xxxxx   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>)
  xxxxx@xxxxx   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

  xxxxx@xxxxx   2001-06-26
Comments
  
  Include a link with my name & email   

Submitted On 05-MAR-2000
matsh
I think it is mindboggling that the JavaDoc team release after release totally ignores the need to easily add 
custom tags.


Submitted On 11-AUG-2000
spalmaaj
We want to add pre- and post-conditions for our Java 
methods, using syntax such as &quot;@precond&quot; and &quot;@postcond&quot;, 
so that this information appears in the Javadoc output.  
But we don't see a way to add user-specific tags in an 
easy, generalized way.  An architectural enhancement to 
Javadoc to support a plug-in facility to allow 
customization such as this should be serously considered by 
the Sun Java team.    



PLEASE NOTE: JDK6 is formerly known as Project Mustang