Paul Winkler wrote at 2004-9-27 19:57 -0400:
... * check base classes for things that need documenting - either add the base class to this API ref, or document any non-overridden methods as part of the derived class docs - not sure how best to do this so i'm handling it on a case-by-case basis.
Many of the base classes are mostly internal. I think, we do not need a complete reference. It would be Oracle like (this is my synonym for "almost unusable"). IMO it is more valuable to document the most relevant classes (and their most relevant attributes and methods) with typical usage rather than document everything but only superficially. I am still convinced that automatic documentation extraction tools (like "DocFinder") are better than manual documentation -- for everything other than the essential concepts and the overview how things play together.
It's a big job, best done one module at a time.
And keep in mind that it is not a one time job... Every release is likely to change minor details. The more details you document now, the more details need checking for new releases. Do not do it! Document only the most essential classes (and how they fit with one another). Reject any request for a complete documentation. Link to automatic documentation extraction tools ("happydoc", "epidoc", "DocFinder") for people that want more details.... -- Dieter