United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4750173 : stddoclet: javadoc -tag option should allow xdoclet tags like @ejb:bean

Details
Type:
Enhancement
Submit Date:
2002-09-19
Status:
Resolved
Updated Date:
2004-06-01
Project Name:
JDK
Resolved Date:
2002-10-25
Component:
docs
OS:
windows_2000
Sub-Component:
doclet
CPU:
x86
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
1.4.2 (mantis)

Related Reports

Sub Tasks

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


                                     
2004-06-14
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.
                                     
2004-06-10
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
                                     
2004-05-29



Hardware and Software, Engineered to Work Together