United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: 4039014 stddoclet: Tag listener - Flag misspelled tags while printing custom tags
4039014 : stddoclet: Tag listener - Flag misspelled tags while printing custom tags

Details
Type:
Enhancement
Submit Date:
1997-03-14
Status:
Closed
Updated Date:
2001-11-22
Project Name:
JDK
Resolved Date:
2001-07-13
Component:
docs
OS:
solaris_2.5.1,windows_98
Sub-Component:
doclet
CPU:
x86,generic
Priority:
P5
Resolution:
Fixed
Affected Versions:
1.1,1.2.0
Fixed Versions:
1.4.0

Related Reports
Duplicate:
JDK-4220213 - display custom tags like @return instead of ignoring them

Sub Tasks

Description
This request is the merging of two requests:  Want to flag misspelled
tags as mistakes, but print custom tags.

REQUEST #1
If javadoc encounters a doc-comment tag that it doesn't recognize, such as:

	* @sea java.lang.String

(which is obviously a typographical error), javadoc simply ignores the entire tagged paragraph and neither issues an error message nor includes the text of the paragraph in the output HTML file.

This behavior makes it very difficult for writers of doc comments to debug their work.  So unless the JLS *requires* this behavior (which would be a JLS bug, IMHO), javadoc should at least issue an error message.

REQUEST #2  (from 4039014)
Display custom tags rather than ignoring them.  In the following example,
@precondition should be printed with a bold subheading "Precondition"
with its text following it.

   public class X{
        /**
         * the custom tag is ignored
         * @return this tag is working
         * @precondition this one is not displayed in the doc
         */
        public String Test() {
                    return "test";
        }
   }

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
merlin-beta2

FIXED IN:
merlin-beta2

INTEGRATED IN:
merlin-beta2

VERIFIED IN:
merlin-rc1
2004-06-14 
SUGGESTED FIX

Proposed solution is to have the user create a tag listener
which indicates the text to be used for the subheading and
the format for the text.  All tags that do not have listeners
would then print a warning such as:

   "Warning: Unrecognizable tag @<tag-name> ignored"
2004-06-11 
EVALUATION

A doc checker doclet should be written.
robert.field@Eng 1997-12-08

Alan, is this something you can add to your docchecker doclet?
Perhaps provide a file listing all valid tags against which you
can check.
doug.kramer@Eng 1998-04-03

Reassigning to Eric, since he's now working on DocCheck doclet.
doug.kramer@Eng 1998-07-29

Although DocChecker could parse the text of the comment to identify
such errors, it would be redoing work that JavaDoc is already doing.
JavaDoc's recognizer should see * then @ and if it then does not
see a recognized keyword, it should generate an error.
Reassigning to the JavaDoc team, by way of Doug. (Possibly Atul should
get it?)
eric.armstrong@eng 1998-08-17

Making this change would require that the developer create a list of 
valid tags that javadoc inspects, since we now allow developers to make 
up their own custom tags.  Changing to P5, since this won't happen
this release.
doug.kramer@eng 1998-08-17

I am combining this request with that of allowing the printing custom tags
through a tag listener, as suggested at Javadoc BOF at JavaOne '99.
doug.kramer@Eng 1999-09-21

I am reassigning to jamieh@eng because this does not require any tool or
API support.

neal.gafter@Eng 2001-02-27

Request #1, emitting a warning for misspellings, is something Jamie can do
now that he has implemented custom tags (which was request #2).
doug.kramer@Eng 2001-06-28

This RFE has been implemented.  Location of fix:

CustomTagFactory.java
AbstractSubWriter.java
ConstructorSubWriter.java
HtmlStandardWriter.java
MethodSubWriter.java
standard.properties

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

This RFE has been implemented.  The CustomTagFactory now has a method to check an array of Tags[] to make sure that they are all valid tags.  If any tags are unknown, an error message like this one is printed:

/home/jamieh/stddoclettests/sample-src/com/package1/Class1.java:65: warning - Warning - @sea is an unknown tag.

jamie.ho@Eng 2001-07-06
2001-07-06


Hardware and Software, Engineered to Work Together