Name: jk109818 Date: 12/09/2001
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)
======================================================================