JDK documentation

[Andrew John Hughes]

On 10/01/2008, Debra Scott <Debra.Scott at sun.com> wrote:
> All,
>
> I apologize for not being clear on my original post.
>
> The JDK documentation, that provided in the zip file we
> refer to as the JDK documentation bundle, includes:
>
> * API docs (javadocs, which are already open source as they are
>     derived from the .java source files) -- I'm not referring to these
>     as you already have access to changing these as part of source code
>     contributions/fixes
>

As others have said, these can't be changed easily as they form the
specification for the Java platform.  Indeed, they are the basis for
other implementations such as GNU Classpath.  It's tricky, because you
do really need another layer of API documentation that documents the
local implementation issues.  Many a time when working on GNU
Classpath it's been a case of 'that sounds nice, but how would you
actually implement it?' or in using it 'so how does this actually
work?'  An example is the cases where there is an interface as part of
the specification and then implementations of that are dependent on
the JDK.  It hasn't always been clear what you get with the OpenJDK: I
remember reading the printing API, thinking I could use it to
manipulate PDFs, but you couldn't because there wasn't a PDF backend
(there may be now -- this is 2002).  A lot of these issues are solved
partially by the availability of source of course, but are still
issues for end users.

Andrew Haley makes a good point with the JMX example, which I remember
caught us out when implementing that class.  There are certainly cases
where things could be made clearer and more usable without altering
the specification.  There are also some that are downright unusable
e.g. classes in java.beans.beancontext IIRC -- it's a good job they
have a separate and open PDF spec!

> * guides documentation (for example, see
> http://java.sun.com/javase/6/docs/technotes/guides/)
>
> * tools (for example, see
> http://java.sun.com/javase/6/docs/technotes/tools)
>
>
> Do most of you only use the API docs and  are these the docs you think of?
> If so, maybe it isn't worth the effort to open source the rest of our
> documentation?
>

I think many of us think of the API documentation.  To be honest, the
other two I've not used as much simply because until now I haven't
been using Sun's JDK as it was proprietary.  I guess this is the case
for a lot of GNU Classpath developers, who will have only checked
these docs to see what kind of user interface the equivalent tools in
GNU Classpath should provide.

I'm actually quite surprised that they aren't part of the OpenJDK
source code drop.  That's where GNU Classpath's documentation is held
and it would seem a more appropriate place. Certainly if people are
going to hack on the OpenJDK, then the documentation needs to be kept
in sync with these changes!  Obviously, translation would be another
advantage too now you can pull on a worldwide community of developers
instead of just Sun employees.

>
> -Debbie
>
>
>
> David Gilbert wrote:
> > Hi,
> >
> > Debra Scott wrote:
> >
> >> Hi All,
> >>
> >> I'd like to get people's thoughts on the documentation
> >> for the JDK platform.
> >>
> >> * How many people feel it is important for the the docs to be open
> >>    sourced so the community can contribute to them?
> >
> > Very important.
> >
> >>
> >>  * How many people have seen at least one occasion
> >>    where they would have added something to the
> >>    documentation, or made a correction, if they
> >>    had been able? (a large or small percentage?)
> >
> > In the API docs, I've often spotted corner cases that aren't
> > documented.  In the past, I've documented these in the GNU Classpath
> > API.  I should probably start submitting patches to OpenJDK for these,
> > but I wonder if that's very efficient because the changes are small and
> > the process is not so lightweight as we had for GNU Classpath (that's
> > not a criticism, it's just an observation, because I understand the need
> > for greater rigor in the OpenJDK process).
> >
> >>  * Given that we need documentation in a structured
> >>    format that allows for content sharing and multiple
> >>    delivery vehicles, does anyone have any recommendations
> >>    for a system that is both easily editable, like a
> >>    Wiki, and easily repurposable, like XML-structured
> >>    docs?
> >
> > A few years ago, the guys at JavaLobby started an excellent initiative
> > called JDocs.  They loaded up the Javadocs for the JDK and invited the
> > community to annotate them with useful pointers, sample code etc.  Sun
> > (or its lawyers) unfortunately squashed the initiative and it more or
> > less died (JDocs is still there, but the project seemed to lose momentum
> > after the Java SE APIs were removed).  Maybe you could get in touch with
> > Rick Ross and Matthew Schmidt at Javalobby and ask them about it...an
> > perhaps inject some new life into JDocs.
> >
> > Regards,
> >
> > Dave Gilbert
> > http://www.jfree.org/
>
> --
>
> ==========================================================================
> Debra Scott                                 39 Golden Wheat Ln
> Manager of Java SE Documentation            Wrightstown, WI  54180
> Information Products Group                  Phone: 877-219-2362  x51743
> Global Product Development & Operations, Sun Microsystems, Inc
> ==========================================================================
>


-- 
Andrew :-)

Support Free Java!
Contribute to GNU Classpath and the OpenJDK
http://www.gnu.org/software/classpath
http://openjdk.java.net