A JEP draft for documenting the Class Library/JVM interfaces

[Sean Chou]

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
-------------- next part --------------
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.