A JEP draft for documenting the Class Library/JVM interfaces

[Neil Richards]

I am cross-posting this to the hotspot-dev mailing list, as people there
may be interested in this proposed JEP.

Note that the proposal is to document the VM interfaces upon which the
class library relies in the /jdk repository (as opposed to documenting
the interfaces the Hotspot VM provides in the /hotspot repository, in
case there is any discrepancy between these two).

Feedback on this (to the cvmi-dev list, please) would be most welcome.

Regards,
Neil


On Wed, 2012-12-05 at 18:20 +0800, Sean Chou wrote:
> Hi all,
> 
> I'm working with Neil on the project of improving the documentation of
> Class Library/JVM interfaces [1]. We created a simple demo about what
> the documentation work would look like, as well we wrote a JEP draft
> based on the demo.
> 
> We hope to get enough comments and put it into JEP process before
> next Friday(Dec 14).
> 
> Here is the content of the draft(also in attachment):
> 
> 
> Title: Building documents for Class Library/JVM interfaces
> Author:
> Organization: IBM
> Owner:
> Created: 2012/12/01
> Type: Informational
> State: Draft
> Exposure: Open
> Component: core/libs, vm/--
> Discussion: cvmi dash dev at openjdk dot java dot net
> Start: 2013/Q1
> Effort: S
> Duration: S
> Template: 1.0
> Internal-refs:
> Reviewed-by:
> Endorsed-by:
> Funded-by:
> 
> 
> Summary
> -------
> 
> Enable the build infrastructure to build documents for Class Library/JVM
> interfaces
> 
> 
> Goals
> -----
> 
> 1. Enable the build infrastructure to generate documentation for Class
> Library/JVM
> interfaces.
> 2. Document the Class Library/JVM interfaces in a format supported by
> doxygen.
> 
> 
> Non-Goals
> ---------
> 
> This JEP does not cover creating additional documentation.
> 
> 
> Success Metrics
> ---------------
> 
> When docs of jdk is built, the document contains the Class Library/JVM
> interfaces.
> 
> 
> Motivation
> ----------
> 
> Besides JNI and JVMTI, the JVM still has a lot functions defined as
> library/JVM
> interfaces. Creating documentation for these functions can help class
> library
> develpers utilize the functions provided JVM. As well, it will help
> alternative JVM to use RI class library.
> 
> 
> Description
> -----------
> 
> This JEP is to add a build option to build the documents for Class
> Library/JVM
> interfaces. The exported JVM functions in jdk/src/share/javavm/export
> directories are used as the Class Library/JVM interfaces.
> 
> The JEP includes following changes:
> 1. Doxygen will be added as a build dependency.
> 2. The build scripted will be modified to include the option of building
> the document.
> 3. The comment format in library/JVM interfaces needs to be updated to
> doxygen format.
> 4. A doxygen configuration file will be added.
> 
> Here is an example what's the document and configuration file would look
> like.
> The built docs:
>     http://cr.openjdk.java.net/~zhouyx/cvmi/interface_doc/
> An example of commented function:
> 
> http://cr.openjdk.java.net/~zhouyx/cvmi/interface_doc/jvm_8h.html#a05f1ec06295884dbb7519ddcf20f0e56
>     http://cr.openjdk.java.net/~zhouyx/cvmi/comment_modi/
> The configuration file:
>     http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/cvmi.conf
> 
> The configuration file quite long, but most of it is created by template;
> the modification is samll. Following is the template and modification.
>     http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/template.conf
>     http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/config.diff
> 
> 
> Alternatives
> ------------
> 
> Write additional specification to document the interface like JNI and
> JVMTI specification.
> 
> 
> Dependences
> -----------
> 
> It is needed to add doxygen to build dependency, and the library/JVM
> interfaces needs to be documented in doxgen supported format.
> 
> 
> Impact
> ------
> 
> The Class Library/JVM interface will get its documents while building.
> 
> 
> 
> 
> ///////// End
> 
> [1] http://mail.openjdk.java.net/pipermail/cvmi-dev/2012-May/000043.html
> 


-- 
Unless stated above:
IBM email: neil_richards at uk.ibm.com
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU