[JSR348-96] Specifications should be directly available as HTML on the web Created: 29/Aug/11 Updated: 09/Sep/11 Resolved: 09/Sep/11
|Reporter:||Stig Inge Lea Bjørnsen||Assignee:||Unassigned|
|Remaining Estimate:||Not Specified|
|Time Spent:||Not Specified|
|Original Estimate:||Not Specified|
One of the problems with the JSR specifications is that application developers often do not read them or consult them as reference material.
I believe one of the reasons for this is that the specifications aren't directly available on the web as HTML. Today, reading a specification usually requires one to accept the license agreement before downloading the specification as a PDF file.
Contrast this to how easily available the HTTP RFC is at http://tools.ietf.org/html/rfc2616.
I wish we had a similar web site for reading JSRs. The Servlet specification could for instance be available as HTML at http://jcp.org/html/jsr315.
By having predictable URLs parametrized by the JSR number we could have IDEs make the specifications instantly available to developers by right clicking a class and then choose "Open specification".
|Comment by pcurran [ 09/Sep/11 ]|
This is an excellent suggestion, but unfortuately out of scope for JSR 348. Although you say that you want easy access to the specification what you really mean is you want easy access to the documentation. There's a There's a subtle but very important distinction between these two terms.
The specification is the formal statement of required functionality. The click-through licenses are there for a reason - because the right to implement the technology defined in the specification is granted only under certain conditions (that the implementation be compatible, for example.)
Yes - for many JSRs (those that define APIs) the specification is often written in (or contains) Javadoc, which is identical to the documentation for the implementation of the specification. However, for other JSRs (the VM spec, for example) the specification (how the JVM functions) is very different from the documentation (how to invoke it.)
Bottom line: since documentation is an implementation issue and the JCP is concerned with formal requirements, your suggestion is out of scope for this JSR. I suggest you try to find somewhere within the OpenJDK or GlassFish communities to make this suggestion.
I'm closing this issue, but wish you luck in pursuing it elsewhere.