Re: [Cp-tools-discuss] gjdoc: ClassDocProxy vs ClassDocImpl

[Julian Scheid]

Mark Wielaard wrote:
> Shouldn't all ClassDocProxies have been replaced by
> loadScheduledClasses()? If someone could explain the design a bit more,
> that would be very helpfull.

(That someone is probably me. AFAIK besides you and me, nobody
contributed to Gjdoc code yet.)

Short answer: They should, unless they can't be loaded because
the source code is not available, or they needn't be loaded
because the class wasn't specified on the command line and
isn't an "essential" reference which needs to be resolved.
So there are situations when a proxy can't or needn't be
replaced by the actual ClassDocImpl. Obviously SerialTagFieldImpl
doesn't deal correctly with this fact.

This issue may be one I should cope with. I'll have a couple
of hours left tomorrow for working on it and I'll be glad to
care about this, and improve the documentation a bit along
the way. ;)

Long answer follows nonetheless, you asked me to explain
the design. The ClassDocProxy thing definitely needs some
explanation.

While building the internal representation of all classes,
its members and their documentation, Gjdoc has to resolve
class names into references to the corresponding ClassDoc
objects. For example, if it processes java/lang/String.java,
it also has to process java/lang/Object.java in order to
know that String.toString() overrides Object.toString().
(Even if you only specify java.lang.String as class
to-be-documented on the command line, Gjdoc has to
retrieve this information.)

The documentation of a class referenced by a particular
class may have been processed at the time the reference is
encountered, or it may have not. If the class already has
been processed, a ClassDocImpl object is available and the
referencing ClassDoc variable will be pointed to this object.

If the class was not yet processed however, a temporary
ClassDocProxy object will be created and the corresponding
class will be "scheduled", i.e. it will be entered into
a List of classes to be loaded at a later time.
When the class documentation has been loaded eventually
(after Gjdoc processed the source codes for all scheduled
classes), all references to the ClassDocProxy will be replaced
by references to the corresponding ClassDocImpl, if
available.

The scheduling approach avoids problems with circular
dependencies. The proxy approach has the advantage that
the internal representation can be built in one pass
which can save lots of time and memory. One of the
biggest challenges when writing Gjdoc was to find
ways of keeping memory usage low, because it is meant
to be capable of creating docs for _huge_ trees.

Note that some references need to be resolved while others
needn't. For example, superclass references need to be
resolved (i.e. the documentation of the superclass needs
to be accessible) so that the inheritance tree can be
constructed correctly. OTOH classes referenced in method
parameters, method return types or field types needn't be
resolved unless you want to "deeply" generate documentation.
Deep generation doesn't make much sense in most any case
- you quickly end up with docs for hundreds or thousands
of ClassDocs - and therefore isn't supported by Gjdoc.

Because some ClassDocProxies are resolved and some are not,
a call to e.g. ClassDocImpl.typeForString() - can return a
ClassDocProxy reference instead of a ClassDocImpl reference.
Any code calling typeForString() should be prepared for this,
but obviously not all code is.