JDK-4232882 : If omitting *, want to keep indentation within <PRE> code examples
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.2.0,1.2.2
  • Priority: P4
  • Status: Closed
  • Resolution: Fixed
  • OS: generic,windows_nt
  • CPU: generic,x86
  • Submitted: 1999-04-26
  • Updated: 2002-06-27
  • Resolved: 2001-08-07
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 Availabitlity Release.

To download the current JDK release, click here.
Other
1.4.0 beta2Fixed
Related Reports
Duplicate :  
Description

Name: vi73552			Date: 04/26/99


I need to put a code fragment example in my javadoc comments.  I
surround the code fragment with pre tags, but javadoc strips all the
leading spaces.  Is there something else I need to do?

Here's the javadoc comment in question:

/** A vector class optimized for working with ints.

    <p>Like the Vector object, except rather than tracking a dynamic
    array of pointers to different objects, this is simply a
    dynamic array of ints.  The advantage is speed and memory
    savings.<p>

    <pre>

    Example:

        // report longest lines
        TextFileIn f = new TextFileIn("blather.txt");
        IntVector v = new IntVector();
        int longestLine = 0 ;
        boolean done = false ;
        while ( ! done )
        {
            String s = f.readLine();
            if ( s == null )
            {
                done = true ;
            }
            else
            {
                int sLength = s.length() ;
                if ( sLength > longestLine )
                {
                    longestLine = sLength ;
                }
                v.append( sLength );
            }
        }
        f.close();
        System.out.println("The longest lines are on line numbers:");
        int i ;
        for ( i = 0 ; i < v.length() ; i++ )
        {
            if ( v.get( i ) == longestLine )
            {
                System.out.println( i );
            }
        }

    </pre>

    @author Paul Wheaton
*/



My examples ends up like this:


// report longest lines
TextFileIn f = new TextFileIn("blather.txt");
IntVector v = new IntVector();
int longestLine = 0 ;
boolean done = false ;
while ( ! done )
{
String s = f.readLine();
if ( s == null )
{
done = true ;
}
else
{
int sLength = s.length() ;
if ( sLength > longestLine )
{
longestLine = sLength ;
}
v.append( sLength );
}
}
f.close();
System.out.println("The longest lines are on line numbers:");
int i ;
for ( i = 0 ; i < v.length() ; i++ )
{
if ( v.get( i ) == longestLine )
{
System.out.println( i );
}
}


My boss insists that all javadoc comments do not have *'s down the left
edge.  Plus he wants the final html document to look right.



---------------------------

If you use *'s along the left edge, then it does work.  This is a workaround,
but not a fix.
(Review ID: 56873) 
======================================================================

Comments
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: merlin-beta2 FIXED IN: merlin-beta2 INTEGRATED IN: merlin-beta2 VERIFIED IN: merlin-beta3
2004-06-14

PUBLIC COMMENTS <p>When a doc comment omits the preceding * on subsequent lines, the indentation of the lines is preserved in the output. This allows you to cut and paste code samples into your javadoc if you surround them by &lt;pre&gt; and &lt;/pre&gt;. For example: <pre> /** &lt;pre&gt; void f() { return; } &lt;/pre&gt; */ </pre> <p>is now interpreted the same as: <pre> /** * &lt;pre&gt; * void f() { * return; * } * &lt;/pre&gt; */ </pre>
2004-06-10

EVALUATION Actually this issue needs to be handled at Java compiler level. atul.dambalkar@eng 1999-05-04 This would nominally be a change to the Java language and so should be considered carefully. The suggested fix is not correct. robert.field@Eng 2000-02-21 Notice that a code in Suggested Fix is included, although Robert says it is incorrect. I am converting this to an RFE, as I stated in Comments. The request is to honor leading spaces inside <pre> tags. If necessary, add a command line option to do this, to maintain backward compatibility. It would have to account for the fact that the method or class itself is indented -- perhaps it should indent only from the column where the <pre> starts. We get a fair number of requests for this, since people want to just copy and paste their working code into the source file (or out of the source file to test it). doug.kramer@Eng 2001-02-22 There are enough votes and customer calls on this that I believe it should receive some attention. I'll see if I can get it in to Merlin's 2nd beta. neal.gafter@Eng 2001-03-06 This RFE has been implemented. Location of implementation: src/share/javac/com/sun/tools/javac/v8/parser/Scanner.java jamie.ho@Eng 2001-07-17
2001-03-06

SUGGESTED FIX Name: pvC76716 Date: 05/05/99 (Pawel Veselov, ###@###.###) Okay, I am not belong to here, but I am interested. This is not fully a bug, this is a feature. In documentation, there is said, that 'On each of these lines, leading * characters are ignored; for lines other than the first, blanks and tabs preceding the initial * characters are also discarded.' This is how a sort of formatting is done. Nevertheless, this formatting is very weak, so we can get rid of requiring stars before formatted text. The diff is following: Source file : src/share/sun/sun/tools/java/Scanner.java ------- Scanner.java ------- *** /tmp/dtFx1h_ Wed May 5 13:57:55 1999 --- Scanner.java Wed May 5 13:57:38 1999 *************** *** 313,321 **** case ' ': case '\t': ! if (seenstar) { ! putc(ch); ! } ch = in.read(); break; --- 313,319 ---- case ' ': case '\t': ! putc(ch); ch = in.read(); break; ------------------------- end of DIFF This was taken from the jdk port I have here, it's one of 1.8 ports. I don't believe it changed a lot, though. ====================================================================== The above suggested fix will not work, consider the case where there is a leading star - the spaces before it will be included. robert.field@Eng 2000-02-21
2000-02-21