JDK documentation

[Jesse Glick]

David Gilbert wrote:
> I really think there is a need for two versions of the Javadocs, one
> that is a specification (that is, what we have now) and another that
> is "developer documentation".

Has anyone considered using explicitly nonnormative sections? The W3C 
marks sections of printed specifications nonnormative ("informational" 
and not "normative") - examples, motivations, implementation hints, etc.

For NetBeans documentation, we sometimes put blocks of nonnormative text 
in Javadoc. It is a simple matter of using CSS to make such blocks 
appear with a special background color, maybe a vertical banner in the 
gutter saying "NONNORMATIVE", etc. You just put in Javadoc:

/**
  * Returns the frobnitz quotient of this reactor core.
  * Must be in the interval [0,1) and no greater than
  * the frobnitz coquotient.
  * <div class="nonnormative">
  * Most implementations use 0.5.
  * </div>
  */
public float getFrobnitzQuotient() {return 0.5;}

Here is an example of output using a very simple CSS rule:

http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileUtil.html#toFileObject(java.io.File)

I expect it would not be difficult to make a tool which processes 
documentation and strips out all nonnormative sections so as to create 
an official API specification.

(It would be good to check that popular IDEs render the nonnormative 
section specially e.g. in code completion popups.)

> what the Javalobby guys were/are trying to do with JDocs.com

Sort of a JDK Talmud, if you will. The challenge is discoverability: 
docs that the user does not know exist are of no help.

-- 
jesse.glick at sun.com netbeans.org ant.apache.org hudson.dev.java.net
selenic.com/mercurial http://google.com/search?q=e%5E%28pi*i%29%2B1