JDK documentation

[Andrew Cowie]

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

-- 
Andrew Frederick Cowie
Managing Director
Operational Dynamics Consulting, Pty Ltd

We are an operations engineering consultancy focusing on strategy,
organizational architecture, systems review, and change management
procedures: enabling successful use of open source in mission
critical enterprises, worldwide.

http://www.operationaldynamics.com/

Sydney   New York   Toronto   London
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://mail.openjdk.java.net/pipermail/discuss/attachments/20080111/7748e0a5/signature.asc>