JDK documentation

[David Holmes - Sun Microsystems]

Andrew,

But as I said in my other posting it isn't always that simple. What is a 
clarification for you in one method might introduce an inconsistency 
into how something is covered across the class.

Any javadoc changes - beyond blatant typos and html tagging - need to be 
carefully considered, for correctness, clarity and consistency with 
other documentation.

Cheers,
David Holmes

Andrew Cowie said the following on 11/01/08 05:15 PM:
> On Thu, 2008-01-10 at 21:15 +1000, David Holmes 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 ... So any "fixes" to the javadocs would not, 
>> I believe, be acceptable through OpenJDK contributions, unless done as 
>> part of a JSR. 
> 
> I think we need to have a serious look at figuring out a way to
> differentiate between documentation changes that along the way change
> the explanation of the behaviour [and thus, unfortunately, the Java spec
> (sic)] and documentation changes which just improve the documentation
> quality without materially changing the behaviour that is being
> described.
> 
>> 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 
> 
> Indeed.
> 
> Perhaps the "Just Get On With It" pattern might be allowed to apply
> here? ... If people submit patches that make the docs better that don't
> change the definition of the expected behaviour, perhaps those reviewing
> can ease off a bit and merely consider whether they are an
> improvement/clarification (and thus able to be accepted as is) or really
> are a library specification change (in which case, defer to JSR to your
> heart's content, and see ya circa Java 1.14 or so)
> 
> AfC
> Sydney
>