JDK documentation

[Mark Thornton]

David Gilbert wrote:
> David Holmes - Sun Microsystems wrote:
>>
>> But I disagree with what you say about the javadocs. While the 
>> javadoc are part of the source files, they form the specification for 
>> the platform API's and as far as I am aware the specification for the 
>> Java platform is not open-sourced. So any "fixes" to the javadocs 
>> would not, I believe, be acceptable through OpenJDK contributions, 
>> unless done as part of a JSR. Hopefully Mark, or someone else in the 
>> know, could clarify this.
>>
>> I know I've been frustrated over the years by the apparent inability 
>> to get anything but the most trivial typos fixed in the docs, except 
>> during major releases. It would be nice if that could change but I'm 
>> not aware that it has at this stage.
> 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".  The latter is, I believe, what the 
> Javalobby guys were/are trying to do with JDocs.com.  Promoting their 
> existing effort seems worth exploring, in my opinion, especially since 
> it can exist independently of the source code.
>
Some things like platform specific behaviour would be very convenient if 
included as annotations on the Java Doc rather than in some completely 
separate (non existent) document. Others like how to run RMID as a 
service need to be part of the tool documentation.

Mark Thornton