we have access to the commentText, and we can reconstruct the
declarations of the Members.  but neither of those contain enough
information to accurately depict the .java source code.

the output of the Standard doclet provides a convenient reference, but
the final word on the effects of a particular method lies in the code,
not the comments.  we programmers try to ensure that the comments
match the code, but sometimes they can get out of sync (particularly
when developing new code).  and sometimes even well-written comments
are just not enough.

it would be nice to have something as simple as:

	public String MethodDoc.implementationText()
	public String FieldDoc.initializerText()

of course, keeping all those Strings around would consume way too much
memory, and it would be nice to have access to more of the raw code.
perhaps something like:

	public abstract class Doc
	{
	  public String sourceFileName()
	  public long commentOpenPosition()
	  public int  commentFirstPeriodOffset()
	  public int  commentCloseOffset()
	  public int  implementationStartOffset()
	  public int  implementationEndOffset()
	}
	public int MethodDoc.bodyStartOffset()
	public int FieldDoc.initializerStartOffset()

with this interface one could write:

	public String MethodDoc.implementationText()
	{
	  int length = implementationEndOffset() - bodyStartOffset();
	  byte[] buffer = new byte[length];
	  sourceFile().seek( commentOpenPosition() + bodyStartOffset() );
	  sourceFile().readFully( buffer );
	  return new String( buffer );
	}

i know i've goofed up by using the default character encoding - the
String constructor should use the encoding specified on the javadoc
command line.  but i think the general idea is clear, yes?

this suggestion seems to imply increasing the storage size of Doc,
which may cause some concern.  i have submitted a separate feature
request asking that the doclet programmer be allowed to write and use
their own Doc subclasses.  [sorry, i don't know the bug number yet].
if that feature were available, then the storage size issue could be
addressed as follows:

there could be two versions of every Doc, one which does not allocate
extra storage and throws exceptions if you try to use the extra
features, and a "fat" version that implements everything.  example:

	public abstract class Doc {
	  public String sourceFileName()
	    { throw new RuntimeException("not implemented"); }
	}
	public class MethodSourceDoc extends MethodDoc {
	  protected String sourceFileName;
	  public String sourceFileName() { return sourceFileName; }
	}

this would let the doclet programmer allocate memory for the
extra information about the source code file only if the doclet needs
that information.
(Review ID: 25038)
======================================================================

N/A

Dup of 1242492.
  xxxxx@xxxxx   1998-09-10

two items:
first, i botched the methodDoc.implementationText() example code.  in my first
email letter to javadoc@sun.com sourceFile() was a RandomAccessFile.  while
submitting the request for enhancement i realized that keeping those files open
would not be possible - the platform will likely impose a limit on the number
of RandomAccessFiles open concurrently.  therefore i changed Doc to keep only
the sourceFileName(), but i forgot to change the implementationText() example
to match.  it ought to open, seek, read, and then close a new RandomAccessFile
for each invocation of implementationText().  granted, that's not the most
optimal strategy - but it's a reasonable first approximation.
second, the other feature request i mentioned (about how to handle the Doc
memory size issue) is <a
href="/developer/bugParade/bugs/4112794.html">#4112794</a>. 
unfortunately it did not survive evaluation.  perhaps i was wrong to submit
these two requests separately - for the raw source code one to succeed the
memory issue must be addressed.

jeremy calls robert "clueless".

i am very sorry, and i apologize to robert:
robert only slammed my request.
but i responded by slamming robert,
and that was very impolite and not at all helpful.
it was just a gut level response to having my idea dismissed as
"evil" without even one word of explanation.
not to mention that #4112794 was shot down for being "ugly".
i was only trying to be helpful, and the only feedback i get is not-kind
four-letter words.
so, is this suppose to encourage me to continue to try to be helpful?

It's not dup of 1242492. I have the same request. 
	public String MethodDoc.implementationText()
	public String FieldDoc.initializerText()
two simple functions as above is good enough. Please re-
open the bug.