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.


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) 
======================================================================

N/A

> 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:  < xxxxx@xxxxx >
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).

 xxxxx@xxxxx  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 ":".

- xxxxx@xxxxx 

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.

 xxxxx@xxxxx  2004-5-29

Would it be possible to intergrate some of the functions of
XDoclet into javadoc?  One of the biggest problems with both
EJB's and web services in Java is that you have to maintain
the same information in multiple sources.  Java should be
abel to handle these using javadoc and metatags in much the
same way that C# does.  Is there any reason why it doesn't?

> This means that "-tag ejb:bean-a-EJB Bean:" will work.

Fine, but how should tags that contain both ':' and '-' be
escaped then? E.g. there exists an xdoclet tag
@ejb:persistent-field
How about: -tag @ejb:persistent-field@X@"CMP data"
(note the leading @ char that denotes the separation char)

xdoclet now also supports/prefers the standard syntax
@ejb.bean, 
see http://xdoclet.sourceforge.net/using.html - thus it
works well with javadoc 1.4 without warnings.
However there are tags containing a "-" like
@ejb.value-object that might get broken with the changed
-tag behavior.

Tags containing - (dash) such as ejb.value-object definately breaks javadoc.  Any ideas if this will be fixed any time soon?

Tags with dashes (-) still break javadoc (1.4.2_10)
or maybe there's been a remedy created for tihis issue... 
Has it?