Name: rm29839 Date: 02/19/98


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