java version "1.2.2"
Classic VM (build JDK-1.2.2_008, native threads, symcjit)


It would be nice if javadoc recognized HTML comments ('<!-- -->'), so that
sections of text within comment blocks could be (temporarily) removed
from the resulting javadoc HTML output.  I.e., it would nice if we could
"comment out" text within javadoc comments.

A simple example of this is something like:

    /***************************************************************
    * Retrieve the status.
    *
    *<!-- INCOMPLETE
    * @return
    * A status code, which is one of the values: <br>
    * 0 - Okay. <br>
    * 1 - Not okay. <br>
    * ...incomplete...
    *-->
    */

    public int getStatus()
    { ... }

In this example, the method returns a "status code", but we don't yet know
what those codes are, so we simply want to keep a boilerplate placeholder
in the javadoc comment, but otherwise we don't want an actual "Returns"
paragraph in the generated javadoc HTML.

Currently, javadoc ignores HTML comment markups, and simply passes them
through to the generated HTML.  This is sufficient for most javadoc comment
text, but provides undesirable effects when comment tags surround '@tag'
markers.  On the example above, for instance, this has the effect of
generating a "Returns" paragraph in the generated HTML, even though we don't
(yet) want it in the HTML.

Another example is being able to enclose '@since' tags within '<!-- -->'
comments until the associated method is fully functional, at which point we
would remove the '<!-- -->' markers.  In general, though, this should apply
to any section of text within a javadoc comment.
(Review ID: 136999) 
======================================================================

There is no suitable way to comment out (or make invisible) '@tag' tags
within javadoc comments.  The only alternative is simply to omit them,
which typically means that they never get written at all.
======================================================================

Changed synopsis from:
   Javadoc should recognize HTML comment markers

   HTML comment markers should be able to span both the description and tags

As I understand it, HTML is embedded within the text of comments and 
tag arguments.  This request suggests the opposite -- that tags also be
embeddable within HTML comments.  This can currently be done by
putting any characters ahead of and on the same lines as the @return tag:

    /***************************************************************
    * Retrieve the status.
    *
    *<!-- INCOMPLETE -->
    *<!-- @return
    * A status code, which is one of the values: <br>
    * 0 - Okay. <br>
    * 1 - Not okay. <br>
    * ...incomplete...
    *-->
    */

    public int getStatus()
    { ... }

This works even for commenting out other than the first tag:

    /***************************************************************
    * Retrieve the status.
    *
    * @return
    * A status code, which is one of the values: <br>
    * 0 - Okay. <br>
    * 1 - Not okay. <br>
    *<!-- @since ? -->
    */

    public int getStatus()
    { ... }

With the new custom tag features of 1.4.0 (-tag), you
can also now do this, which might be a cleaner way of doing
it.  This has the advantage that each @INCOMPLETE tag
appears as a warning in the terminal's output stream,
and the unfinished text never appears as an HTML comment
in the HTML pages (visible to someone who peeks at the
HTML source).

 
     /***************************************************************
     * Retrieve the status.
     *
     * @INCOMPLETE: @return
     * A status code, which is one of the values: <br>
     * 0 - Okay. <br>
     * 1 - Not okay. <br>
     * ...incomplete...
     */
 
     public int getStatus()
     { ... }

With these two choices, I see no need to introduce a new syntax.

 xxxxx@xxxxx  2002-03-21

Seems like a reasonable solution(s).