United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: 4232882 If omitting *, want to keep indentation within <PRE> code examples
4232882 : If omitting *, want to keep indentation within 
 code examples

Details
Type:
Enhancement
Submit Date:
1999-04-26
Status:
Closed
Updated Date:
2002-06-27
Project Name:
JDK
Resolved Date:
2001-08-07
Component:
tools
OS:
windows_nt,generic
Sub-Component:
javadoc(tool)
CPU:
x86,generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.2.0,1.2.2
Fixed Versions:
1.4.0

Related Reports
Duplicate:
JDK-4321096 - Honor indenting spaces for 
 when no asterisks (*) are present

Sub Tasks

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


Hardware and Software, Engineered to Work Together