JDK documentation

[Eric Armstrong]

Small addition here:

   The DITA document format was specifically designed in a
   way that lets you stay DRY (no repetition), while at the
   same time transcluding relevant bits everywhere they're
   needed. So it's "write once, view everywhere".

Of course, the API comment mechanism doesn't very well lend
itself to a structured XML document format like DITA, but
it is an interesting thought experiment to imagine what such
a thing /would/ look like.

Some possibilities:

  * Conversion of API comments to DITA topics, using the
    topic types already defined at Apache--with an augmentation
    of comment contents to allow for DITA "conrefs"
    (the content-references that implement transclusion)

  * Specialized DITA topics (extensions) that transclude code,
    producing a separation that makes comments editable by
    many, while code is editable by only a few--along with
    an IDE plugin that creates a dynamic editing environment
    which makes them appear as a unified whole.

  * Further application of XML structures to the code, with
    an editor that gives you a fully-integrated outline view
    that you can collapse and expand at will.

Such a system might help to solve a related problem:
The fact that the comments are in the code makes them easily
available and easily edited by coders (which probably explains
why Java has the best API docs on the planet). But at the same
time, the fact that they are divorced from standard documentation
mechanisms makes them harder to linkcheck, spellcheck, do
global substitutions, or apply any of the other publication
tools and procedures that are ordinarily used for documents.

David Holmes - Sun Microsystems wrote:
> I don't want to start a meta-debate on these kinds of changes, but I 
> feel the need to add a couple more comments :)
> 
> Andrew Haley said the following on 11/01/08 12:16 AM:
>> Most of the changes I'd make to the javadocs are clarifications, not
>> changes in intent.  To clarify, here's an example that bit me.
> 
> I understand, but even clarifications are not necessarily 
> straight-forward. The point is that someone, or a group of someones, 
> will have to evaluate all javadoc changes to establish whether the 
> change is truly a "clarification". At the moment all that can be easily 
> fixed is true typos and html tagging.
> 
>> ... So,
>> you can only tell that registerMBean() has this side-effect if you
>> read the whole page.
> 
> I'm afraid (for better or worse) that this is a style of documentation 
> used in many of the JDK libraries. Things that are common across methods 
> are often documented once at the class level eg. "Unless otherwise 
> stated all methods that take a collection object as an argument with 
> throw NullPointerException if the argument is null." And things that are 
> common across classes/types are often documented at the package level - 
> see the java.util.concurrent package (and sub-package) docs.
> 
> There are distinct advantages to writing things correctly once rather 
> than repeating them all over and risk missing some cases, and risk 
> omitting changes if there is a need for change. The requirement of this 
> approach is that the user must read all of the relevant docs ie to 
> understand a method you should first have read read the package docs, 
> then the class docs, and then the method doc.
> 
> 
> Cheers,
> David Holmes


-- 

Eric Armstrong, Document Systems Architect, Sun Microsystems
http://blogs.sun.com/coolstuff
http://www.artima.com/weblogs/index.jsp?blogger=cooltools