JDK-4039014 : stddoclet: Tag listener - Flag misspelled tags while printing custom tags
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.1,1.2.0
  • Priority: P5
  • Status: Closed
  • Resolution: Fixed
  • OS: solaris_2.5.1,windows_98
  • CPU: generic,x86
  • Submitted: 1997-03-14
  • Updated: 2014-05-05
  • Resolved: 2001-07-13
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availabitlity Release.

To download the current JDK release, click here.
Other
1.4.0 beta2Fixed
Related Reports
Duplicate :  
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