Name: rlT66838 Date: 03/13/2000


java version "1.2.2"

1. To reproduce: run Javadoc on the following class.

2. Source code:

public class MyDoc implements Runnable {

  /**
    Convenient way to do nothing. A very simple
    example that does nothing in a separate thread is,
    <PRE>
      new Thread(new MyDoc())
                 .start());
    </PRE>
    */
  public void run() {}

}

Javadoc works rather well in this situation if each line of the doc
comment is prefixed with " * ". But without the leading "*", Javadoc
strips all leading white space.

Even with the leading "*", Javadoc behavior is slightly non-intuitive:
most people follow the "*" with one space, and Javadoc leaves that at
the beginning of the output line, so <PRE> text "always" has a leading
space (1 more than expected).

Even the "*"s are hard for people trying to maintain Javadoc comments
because they get in the way when moving text from line to line.

It would be really nice if Javadoc would keep a reference level of indentation
and strip only that many leading spaces. For example, it could use the
indentation of the first line following the /** as the reference, and never
strip more than that many spaces from following lines. It could adjust
for leading "*" by not including spaces before the first "*" in this
calculation.
(Review ID: 102367)
======================================================================