A JEP draft for documenting the Class Library/JVM interfaces

[Steve Poole]

hi Sean ,  thanks for posting this.  I've copied in Mikael Vidstedt as I think he'll be interested (and probably not watching cvmi :-) )


On 5 Dec 2012, at 10:20, Sean Chou <zhouyx at linux.vnet.ibm.com> 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
> 
> -- 
> Best Regards,
> Sean Chou
> <doc_vmi_jep_draft.txt>