JDK documentation

[Eric Armstrong]

It was just pointed out to me that not everyone knows the
acronyms I used:

   DRY -- Don't Repeat Yourself (reuse, reuse, reuse)
   DITA -- Darwin Information-Typing Architecture
     An open source XML format developed at IBM.
     It lets you create small modular bits of info
     that you glue together to make docs. The modular bits
     have "types" (hence, information-typing), and you
     can extend those types to create versions for
     special purposes (hence Darwinian). Significantly
     brilliant. Harder than HTML to edit, but you can
     slice and dice your content, tag it with metadata,
     produce HTML, PDF, Help, DocBook, and more.

Eric Armstrong wrote:
> 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