Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

#166 JavadocTagInfo: broken documentation comments

closed
None
5
2012-10-10
2009-04-28
No

Building the javadoc documentation for checkstyle using sun JDK 1.6.0_13 causes the following exception to occur. It seems to get caught, so most of the documentation is intact, but the documentation for JavadocTagInfo lacks the class description text. With javadoc called directly, not from within ant, the exception stack trace immediately follows the line for the file causing the problem:

Generating .../trunk/checkstyle/target/docs/api/com/puppycrawl/tools/checkstyle/api//FullIdent.html...
Generating .../trunk/checkstyle/target/docs/api/com/puppycrawl/tools/checkstyle/api//JavadocTagInfo.html...
com.sun.tools.doclets.internal.toolkit.util.DocletAbortException
at com.sun.tools.doclets.internal.toolkit.taglets.ValueTaglet.getFieldDoc(ValueTaglet.java:108)
at com.sun.tools.doclets.internal.toolkit.taglets.ValueTaglet.getTagletOutput(ValueTaglet.java:144)
at com.sun.tools.doclets.internal.toolkit.taglets.TagletWriter.getInlineTagOuput(TagletWriter.java:201)
at com.sun.tools.doclets.formats.html.HtmlDocletWriter.commentTagsToString(HtmlDocletWriter.java:1446)
at com.sun.tools.doclets.formats.html.HtmlDocletWriter.printCommentTags(HtmlDocletWriter.java:1412)
at com.sun.tools.doclets.formats.html.HtmlDocletWriter.printInlineComment(HtmlDocletWriter.java:1397)
at com.sun.tools.doclets.formats.html.ClassWriterImpl.writeClassDescription(ClassWriterImpl.java:216)
at com.sun.tools.doclets.internal.toolkit.builders.ClassBuilder.buildClassDescription(ClassBuilder.java:262)

The cause is that the documentation of the class refers to the {@value} tag, but doesn't properly escape that tag. Looking at the documentation, there are a lot of places where javadoc tags are escaped either by

 or by @ instead of @. The former greatly impairs legibility due to the added paragraph and has absolutely no effect on current javadoc implementations, while the latter decreases legibility of the comment itself somewhat. For some reason, the opening brace matching the closing one is missing from all inline tag descriptions.

The solution to all of this in my opinion should be proper use of the {@code} tag, which has escaping of nested javadoc tags as part of its job description. The attached patch does so, getting rid pf all those

 and cleaning up some more.

Discussion

  • Good catch. Your patch does fix up javadoc generation errors. What is interesting is that eclipse 3.4 complains of malformed javadoc tags (which is probably incorrect). I suppose it is more important to have Sun's javadoc tool working correctly anyway.

    Thanks for patch. I will apply it for our upcoming release.