Documenting the interfaces to the VM

Thu May 10 11:08:54 UTC 2012

Hi all,
As previously trailed [1], I'm looking to work on improving the
(sometimes scarce) documentation of the interfaces to the VM.

In doing this, I hope to produce a clear definition that any alternative
(or subsequent) VM implementation can follow. 

Also, it will hopefully expose any "rough edges" - places where the user
or application developer is unnecessarily exposed to VM implementation
details - and suitable resolutions considered.

I'm looking to do this work primarily in the CVMI project, and on the
'cvmi-dev' mailing list. As the documentation gets fleshed out, I expect
that other potentially-interested parties (Hotspot, Zero, porting
projects, Jigsaw?) will consider consuming the resulting changes.

In particular, I expect there will be a healthy interchange between this
work and that of the newly-proposed PPC/AIX porting project [2], given
their stated interest in this area.

Obviously, any assistance (particularly in review, to make sure I'm not
writing complete fiction!) will be warmly welcomed :)

For native interfaces, I'm proposing the use of 'doxygen' [3] as a means
to produce the formatted documentation. This allows the documentation
source to be held in a Javadoc-like style alongside the code in the
header files themselves - a familiar and, I hope, fairly uncontroversial
approach.

Please let me know any suggestions or questions you have about this.
Thanks,
Neil

[1] http://mail.openjdk.java.net/pipermail/discuss/2012-May/002622.html
[2] http://mail.openjdk.java.net/pipermail/discuss/2012-May/002618.html
[3] http://www.doxygen.org

-- 
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