JDK documentation

David Holmes - Sun Microsystems David.Holmes at Sun.COM
Thu Jan 10 11:15:45 UTC 2008


Debra,

Thanks for clarifying that it was the guides you meant - I totally agree 
they should be opened up and expanded/improved by the community.

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.

Cheers,
David Holmes

Debra Scott said the following on 10/01/08 08:53 PM:
> As javadoc is already open source, I'm not talking about those docs
> (which are fixed through the source code files)
> 
> I'm talking about the JDK guide documentation that is part
> of the JDK documentation download bundle
> 
> -Debbie
> 
> Stephen Colebourne wrote:
>> Debra Scott wrote:
>>
>>> 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?
>>
>>
>> Are you referring to javadoc, or other docs?
>>
>>>  * 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?)
>>
>>
>> I have had plenty of simple javadoc fixes I've seen and might have 
>> made (like documenting what happens with null). But I suspect that is 
>> not what you are driving at.
>>
>> Stephen
> 



More information about the discuss mailing list