Re: [Cp-tools-discuss] Gjdoc inheritance information

[C. Brian Jones]

On Mon, 2004-11-22 at 12:13, Julian Scheid wrote:
> 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. 

I don't think this is a viable option.  You will eventually want to deal
with linking to additional javadoc locations just like javadoc does.  It
would be interesting to see if when you doc something with javadoc and
link the java.lang docs to the online or local j2se 1.2 javadoc if you
still get the getCause() peculiarity, maybe even an invalid URL caused
by the use of reflection or if it does something else.  The javadoc
documentation says it only refers to the package-list file at the given
URL.

> #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...

This sounds like the better approach to me.


> #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.

Doesn't sound like Sun bothered here, but there is always the option of
adding this functionality later.  Of course on a project like Classpath
how would you ever get this information unless your tool looks at @since
tags and those all are absolutely correct in Classpath?  And then what
of deprecated and removed methods, which you your tool would know
nothing about if they no longer existed in source code but you wanted to
doc this as if they did as in some old version of the JVM?  This sounds
a bit difficult to me.

Brian
-- 
Brian Jones <address@hidden>