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




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

N/A

Actually this issue needs to be handled at Java compiler level.
 xxxxx@xxxxx  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.
 xxxxx@xxxxx  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).
 xxxxx@xxxxx  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.

 xxxxx@xxxxx  2001-03-06

This RFE has been implemented.  Location of implementation:

src/share/javac/com/sun/tools/javac/v8/parser/Scanner.java
 xxxxx@xxxxx  2001-07-17

Why would this be handled by the java compiler?
The source is read by javadoc.  Does javadoc
use routines that are common to the compiler?

> Why would this be handled by the java compiler?
> The source is read by javadoc.  Does javadoc
> use routines that are common to the compiler?

Yes, javadoc is built on top of the java compiler.