JDK-6359300 : {@code} tag mistakenly strips out leading spaces of first line
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 5.0,6
  • Priority: P4
  • Status: Resolved
  • Resolution: Duplicate
  • OS: solaris_10,windows_xp
  • CPU: x86,sparc
  • Submitted: 2005-12-06
  • Updated: 2014-05-05
  • Resolved: 2013-06-18
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.
JDK 8
8Resolved
Related Reports
Duplicate :  
Description
FULL PRODUCT VERSION :
java version "1.5.0_05"

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

ADDITIONAL OS VERSION INFORMATION :
This problem happens on all operating systems

A DESCRIPTION OF THE PROBLEM :
The recommended way to include muti-line code samples that contain type parameters is to use <PRE> followed by {@code}.  The first tag keeps the indentation/newlines intact, while the second prevents angle brackets '<' from being interpreted as HTML.

However, this combination of tags causes leading spaces to be stripped out, preventing the first line from being properly indented.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Save the following java code to HelloWorld.java and run javadoc on it
(javadoc HelloWorld.java -d docs).  Then open docs/HelloWorld.html and notice the resulting first line of the code is not indented (but should be)

--------------------- HelloWorld.java ------------------------
/**
 * Here is a code example:
 *<PRE>{@code
    static void expurgate(Collection<String> c) {
    }
 *}</PRE>
 * End of example
 */
public class HelloWorld {
}
---------------------------- end of file -------------------------------

For more info, see {@code}:
http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/javadoc.html#{@code }

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
(I don't know if this bug report will display the spacing here faithfully,
so I'll put a dot (.) where a leading space should actually appear)
This is what the generated web page should look like:

----------------------------------------------
Here is a code example:

....static void expurgate(Collection<String> c) {
....}

End of example
----------------------------------------------
ACTUAL -
This is what the generated web page actually looks like:

----------------------------------------------
Here is a code example:

static void expurgate(Collection<String> c) {
....}

End of example
----------------------------------------------

ERROR MESSAGES/STACK TRACES THAT OCCUR :
(none)

REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
See the "Steps to Reproduce" above.
---------- END SOURCE ----------

CUSTOMER SUBMITTED WORKAROUND :
WORKAROUND: Now run javadoc on this -- notice the resulting first line is properly indented

--------------------- HelloWorld.java ------------------------
/**
 * Here is a code example:
 *<PRE>{@code \u0000    // Removes words
    static void expurgate(Collection<String> c) {
    }
 *}</PRE>
 * End of example
 */
public class HelloWorld {
}
---------------------------- end of file -------------------------------

NOTES:
The null character (\u0000) apparently prints as a zero-width character, which
enables the following spaces to not be stripped out.

Adding a newline between <PRE> and the first character (/) would cause an unwanted newline to appear in the output.

Comments
This bug has been resolved in 8 as a part of fix provided in 8002387
18-06-2013

EVALUATION @code was not intended for multi-line use, but it comes so close to working for that anyway that it would be a shame not to come up with a solution to this one glitch. Problem: the syntax of javadoc tags requires that all whitespace immediately following the tag name be ignored. Carving out an ad-hoc exception would not be reasonable. Possible fix: spec the @code tag (and @literal) to ignore some particular sentinel if that sentinal appears at the start of the tag's text. For example: <pre>{@code IGNOREME hi there}</pre> Hopefully something more appealing than IGNOREME could be found. A null character (\u0000) perhaps? That would be reminiscent of the submitter's workaround, except that the null would not appear in the generated docs.
07-06-2006