Documenting the interfaces to the VM

[Volker Simonis]

Hi Neil,

this project sounds very interesting and promising!

What do you exactly mean by documenting the native interfaces with Doxygen?
Do you propose to put Doxygen comments around the "JVM_*" functions in
"jvm.h" for example?

As this file is duplicated under "hotspot/src/share/vm/prims/jvm.h"
and "jdk/src/share/javavm/export/jvm.h" where do you would suggest to
place the documentation?

Or asking the other way around: would you propose to start this
project from the JDKs point of view (i.e. what does the JDK require to
run) or from the VM's perspective (i.e. what does the VM want to
provide)?

Regards,
Volker


On Thu, May 10, 2012 at 1:08 PM, Neil Richards <neil.richards at ngmr.net> wrote:
> 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
>