JDK-4750173 : stddoclet: javadoc -tag option should allow xdoclet tags like @ejb:bean
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: windows_2000
  • CPU: x86
  • Submitted: 2002-09-19
  • Updated: 2014-05-05
  • Resolved: 2002-10-25
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 Availability Release.

To download the current JDK release, click here.
Other
1.4.2 mantisFixed
Description
Name: rmT116609			Date: 09/19/2002


FULL PRODUCT VERSION :
java version "1.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)

also:

java version "1.4.1"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1-b21)
Java HotSpot(TM) Client VM (build 1.4.1-b21, mixed mode)

FULL OPERATING SYSTEM VERSION :
Microsoft Windows 2000 [Version 5.00.2195]

A DESCRIPTION OF THE PROBLEM :
javadoc suggests to use '.'s in custom tags, whereas the popular xdoclet tool
(http://xdoclet.sourceforge.net/) uses ':'s.

Thus each javadoc run issues warnings like
MyBean.java:123: warning - @ejb:bean is an unknown tag.

These warnings can not be turned off calling javadoc -tag ejb:bean:X
because the -tag option uses the : as separator which cannot be quoted.

Instead javadoc tells:
Note: Custom tags that could override future standard tags:  @ejb. To avoid potential overrides, use at least one period character (.) in custom tag names.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
run javadoc on a source file with an xdoclet tag, e.g. @ejb:bean

EXPECTED VERSUS ACTUAL BEHAVIOR :
Just an issue of warnings, no functional defect.

However: the question that arises is when designing a custom javadoc/xdoclet
tag library, whether to follow the xdoclet (@xy:tag) or Sun (@xy.tag) style.


ERROR MESSAGES/STACK TRACES THAT OCCUR :
MyBean.java:123: warning - @ejb:bean is an unknown tag.


REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
/**
 * @ejb:bean type="Stateless" name="MyBean"
 */
public class MyBean implements SessionBean
{
}

---------- END SOURCE ----------

CUSTOMER WORKAROUND :
ignore the warnings.
(Review ID: 164712) 
======================================================================
Comments
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: mantis FIXED IN: mantis INTEGRATED IN: mantis mantis-b05
14-06-2004
PUBLIC COMMENTS I have fixed this bug. The standard doclet now allows '-' as an alternate seperator for the tag option. For example, "-tag todo:a:To Do:" is equivalent to "-tag todo-a-To Do:". This means that "-tag ejb:bean-a-EJB Bean:" will work.
10-06-2004
EVALUATION > Doug Kramer wrote: > Have you tried: > > javadoc -tag "ejb:bean":X > > There is a bug in 1.4.1 and 1.4.0 where the X term does not work unless it > is followed by a name, so also try: > > javadoc -tag "ejb:bean":X:bean Michael Pichler wrote: <###@###.###> I tried, but it did not work. Either the quote " is interpreted solely by the shell or - when quoted - javadoc thinks the user means a tag @"ejb (still truncated at the first ":" character, not searching for a matching "). Perhaps the -tag argument parsing should allow for a quoting character, e.g. -tag ejb\\:bean:X (two \\ on the commandline such that the shell passes one \ to javadoc). ###@###.### 2002-09-24 > Doug wrote: > Can you think of any objection to allowing the colon in such a tag name? Jamie replied: I can't think of any reason not to allow this. The tool has always been able to handle tags with colons in them. If the tool allows this, then the doclet should support this. > I realize the colon is not allowed in class names, and wonder if we > should keep the same constraint for tag names. > > The colon in custom tags that are interpreted by a third-party doclet > called "xdoclet", so there is some benefit to allowing the use of a > colon, as those tags could also be used by the standard doclet. It sounds like there is a need for our doclet to support this. If people are already using tags like this, our doclet should be able to handle them. > The complication seems to be that the colon is passed in on the > command line as: > > javadoc -tag "ejb:bean":a:bean > > where it is interpreted by some shells rather than passed along. > Is there an escape character that would work to escape the colon, > such as "\:" or "\\:"? I think that we would have to use "\\:" because the first \ is probably thrown away by the shell before the string is passed to Javadoc. Maybe we can support "-" as a seperator. For example: -tag "ejb:bean-a-EJB Beans:" If "-" is found in the string, it is assumed that "-" is the seperator, not ":". ###@###.### We should add some documentation for this. We no longer support dashes as seperators for the tag option due to the regression it caused that we fixed in Nov 2003: 4920381: REGRESSION: Tag name containing dash not allowed. The colon is now ALWAYS the seperator. If the user wants a colon in their tag name, they have to escape it using the backslash. For example: -tag ejb\:bean:Beah:a It was a bad idea to use an alternate seperator. That just introduces a different bug. I think escaping is the right fix. ###@###.### 2004-5-29
29-05-2004