[Cp-tools-discuss] Gjdoc inheritance information

[Julian Scheid]

There used to be a notice printed by gjdoc along the lines of "for now,
make sure to include the core classes". I removed this notice, but it
turns out that it was in there for a reason.

Let's say you use both Javadoc and Gjdoc to document the following 
class, without specifying anything on the command line other than the
name of the package to be documented:

  package foo;
  class Bar extends java.io.IOException { }

"javadoc foo" will produce the following inheritance tree for "Bar":

java.lang.Object
  extended by java.lang.Throwable
      extended by java.lang.Exception
          extended by java.io.IOException
              extended by bar.Foo

and sections titled "Methods inherited from class java.lang.Throwable"
and "Methods inherited from class java.lang.Object".

Note that in the javadoc output, the methods in Throwable include
getCause() even if "-source 1.2" is specified on the javadoc command
line, although getCause is a method introduced with Java 1.4. So javadoc
doesn't seem to pay that close attention to the source flag...

"gjdoc foo" won't produce an inheritance tree for class Bar at all, nor
will it list the methods inherited from superclasses, unless you include
the Classpath java.lang and java.io packages on the command line. In
this regard gjdoc behaves differently from javadoc. Currently, gjdoc
simply ignores unavailable superclasses, while Javadoc falls back to
some information resource which is unspecified and unknown, but is
likely gathered using reflection from javadoc's runtime environment.

The question is how to deal with this situation. I can imagine the
following solutions.

****

#1: Leave everything as-is. If the user needs full inheritance
information, he has to include all relevant source codes on the gjdoc
command line. Failing this, the appropriate information isn't included
in the output.

On the downside, this places an additional burden on the user, and it 
doesn't follow the rule of least surprise. On the upside, documentation
can be 100% accurate if the user specifies the correct source
directories. Another upside is that no code has to be written and
maintained.

****

#2: If a superclass isn't available in source code, but is available
through some class loader, fall back to using reflection. This would be
similar to the Javadoc approach I guess, since the output would depend
on the class versions available to the gjdoc runtime instead of the
actual classes inherited by the documented class (compare to the
getCause peculiarity).

On the downside, documentation deviates from the correct documentation
iff the gjdoc runtime environment deviates from the target runtime
environment of the document class. On the upside, behaviour is
compatible to javadoc.

****

#3: Ship the XML documentation for (different versions of?) Classpath
with gjdoc and use it as a fall-back for inheritance information if a
source code is not available.

On the downside this means maintenance hell. On the upside, if
maintained well (not that I want to do that job) the output can be
accurate without burdening the user with anything other than setting the
-source option (or a corresponding -gnu-classpath-version" option for
that matter).

****

Please let me know your thoughts about this.

Julian