 
Use of JCP site is subject to the
JCP Terms of Use and the
Oracle Privacy Policy
 |
|
 JSRs: Java Specification Requests
JSR 260: JavadocTM Tag Technology Update
This JSR has been Withdrawn
The following information has been updated from the original request.
2010.02.15
Maintenance Lead: Oracle America, Inc. Contact: Danny Coward
E-mail address: danny.coward Telephone: +1 408 276 7049 2006.12.18: The following information has been updated from the original request. 2006.12.18: Specification Lead: Scott Seligman E-Mail Address: scott.seligman Telephone Number: +1 408 276 7278 Fax Number: - 2005.08.22Specification Lead: Amy Fowler, Kathy Walrath E-Mail Address: amy.fowler Telephone Number: +1 408 276 7077, +1 408 276 7610 Fax Number: -
Original Java Specification Request (JSR)
Identification |
Request |
Contributions |
Additional Information
Section 1. Identification Submitting Member: Sun Microsystems, Inc. Name of Contact Person: Denis Mikhalkin E-Mail Address: Denis.Mikhalkin@sun.com Telephone Number: +7 812 334 2835 Fax Number: +7 812 334 2913 Specification Lead: Denis Mikhalkin E-Mail Address: Denis.Mikhalkin@sun.com Telephone Number: +7 812 334 2835 Specification Lead: Amy Fowler, Kathy Walrath E-Mail Address: amy.fowler Telephone Number: +1 408 276 7077, +1 408 276 7610 Fax Number: -
Original Java Specification Request (JSR)
Identification |
Request |
Contributions |
Additional Information
Section 1. Identification Submitting Member: Sun Microsystems, Inc. Name of Contact Person: Denis Mikhalkin E-Mail Address: Denis.Mikhalkin@sun.com Telephone Number: +7 812 334 2835 Fax Number: +7 812 334 2913 Specification Lead: Denis Mikhalkin E-Mail Address: Denis.Mikhalkin@sun.com Telephone Number: +7 812 334 2835 Fax Number: +7 812 334 2913 Initial Expert Group Membership: Sun Microsystems, Inc. Supporting this JSR: Sun Microsystems, Inc. Section 2: Request
2.1 Please describe the proposed Specification:Since 1995 the javadoc tag technology has been used by Java API authors to provide embedded documentation within Java comments. The javadoc technology has held up remarkably well as the platform has evolved. However javadoc was originally designed for documenting comparatively small and simple APIs. Today's Java class APIs can be extremely rich and varied, and it can be difficult for developers to navigate through the raw javadoc documentation for the many hundreds of direct and inherited methods in large classes. It therefore appears appropriate to upgrade the javadoc tag technology to provide a richer set of tags to allow more structured presentation of javadoc documentation. This JSR will investigate various improvements to javadoc tags, including for example:
* semantical index of classes and packages * distinction of static, factory, deprecated methods from ordinary methods * distinction of property accessors from ordinary methods * combining and splitting information into views * embedding of examples, common use-cases along with Javadoc This JSR will also investigate possible representations of the document generated by the Javadoc tool from Javadoc comments using new tags. 2.2 What is the target Java platform? (i.e., desktop, server, personal, embedded, card, etc.)This JSR specifies new platform-independent javadoc tags. 2.3 The Executive Committees would like to ensure JSR submitters think about how their proposed technology relates to all of the Java platform editions. Please provide details here for which platform editions are being targeted by this JSR, and how this JSR has considered the relationship with the other platform editions.Any edition might use this specification. The initial plan is to apply it to parts of J2SE. 2.4 Should this JSR be voted on by both Executive Committees?No 2.5 What need of the Java community will be addressed by the proposed specification?Java developers need better documentation, where it is easier to navigate and locate information on specific topics. 2.6 Why isn't this need met by existing specifications?This specification will update and extend the existing javadoc tags as described in 2.1 2.7 Please give a short description of the underlying technology or technologies:Javadoc tags. HTML, JavaScript 2.8 Is there a proposed package name for the API Specification? (i.e., javapi.something, org.something, etc.)N/A 2.9 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?No 2.10 Are there any security issues that cannot be addressed by the current security model?No 2.11 Are there any internationalization or localization issues?No 2.12 Are there any existing specifications that might be rendered obsolete, deprecated, or in need of revision as a result of this work?This JSR is supposed to extend the Javadoc tags specification and recommended practices. See also 3.1 2.13 Please describe the anticipated schedule for the development of this specification.1) 30 November - 30 March, 4 months
2) 30 March - 30 June, 3 months 2.14 Please describe the anticipated working model for the Expert Group working on developing this specification.The majority of EG business will be conducted via the mailing list and forum with occasional conference calls if the EG feels live discussion is necessary. 2.15 It is important to the success of the community and each JSR that the work of the Expert Group be handled in a manner which provides the community and the public with insight into the work the Expert Group is doing, and the decisions that the Expert Group has made. The Executive Committees would like to ensure Spec Leads understand the value of this transparency and ask that each JSR have an operating plan in place for how their JSR will address the involvement of the community and the public. Please provide your plan here, and refer to the Spec Lead Guide for a more detailed description and a set of example questions you may wish to answer in your plan.I plan to establish a public web-site with public/EG forums (TikiWiki), file uploads for prototypes and specification. Read access is closed before the public review stage, open after that. Write access is only after registration at public review stage. The discussion will flow mostly around two topics - means to describe the information in source files, ways to represent it visually, - and the impact of both. Both may be presented efficiently on a web site using text/HTML/images. 2.16 Please describe how the RI and TCK will de delivered, i.e. as part of a profile or platform edition, or stand-alone, or both. Include version information for the profile or platform in your answer.Because this JSR will not define API specifications, there will not be a TCK. In order to test the usefulness of the new tags, Sun will deliver a "reference implementation" javadoc tool that will demonstrate one way of using the new tags to generate structured documentation. It is intended that this tool will be delivered as part of the J2SE Mustang (6.0) release. 2.17 Please state the rationale if previous versions are available stand-alone and you are now proposing in 2.13 to only deliver RI and TCK as part of a profile or platform edition (See sections 1.1.5 and 1.1.6 of the JCP 2 document).N/A 2.18 Please provide a description of the business terms for the Specification, RI and TCK that will apply when this JSR is final.There will be no TCK. It is intended that the RI will be delivered at zero charge as a component of a J2SE platform release. Section 3: Contributions
3.1 Please list any existing documents, specifications, or implementations that describe the technology. Please include links to the documents if they are publicly available.1) The Javadoc tool specification
[1] Javadoc reference pages
[2] Doclet API specification:
[3] Doc Comment specification (outdated): 2) Commenting and annotating of source files
[4] How to Write API Specifications - J2SE Conventions
[5] How to Write Doc Comments for Javadoc - Sun Conventions 3) Other
[6] More Javadoc tool info
[7] Collected proposals, prototypes, RFEs: 3.2 Explanation of how these items might be used as a starting point for the work.The problems and solutions, presented in [7] will become the topics for discussion and specification during JSR development process. The current specification [1] will be used as a basis. Section 4: Additional Information (Optional)
4.1 This section contains any additional information that the submitting Member wishes to include in the JSR.
|
