Documenting the interfaces to the VM

[Neil Richards]

On Thu, 2012-05-10 at 15:56 +0200, Volker Simonis wrote:
> Hi Neil,
> 
> this project sounds very interesting and promising!
> 

Hi Volker,
Thanks for the encouragement :)

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

Yes, that is a good example of what I'm thinking about.

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

Aww, you've anticipated my first concrete question!

It seems unfortunate that declarations are duplicated in these two
files, especially given that the two files are not quite duplicates of
each other (despite comments suggesting that they are).

I can see that having a version in each repo is useful (enabling
developers to build each repo in isolation), but I think that working
towards them being strict duplicates of each other would be a sensible
move (so one can easily work out if they're "in-step" by diff'ing /
cmp'ing them).

Whilst not quite fully conforming to the "Don't Repeat Yourself"
principle [1], it would at least adhere to the associated "If You Must
Repeat Yourself, Only Do So Trivially" principle that I've just made up.

(Yeah, I know, it needs a more catchy acronym that's less like someone
sneezing).

Extra functions provided by the VM, but not required by the JDK, would
then better be captured in separate header file. Doing this would also
make it clearer when apparently VM-agnostic code reaches across to use
implementation-specific functionality.

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

As my aim is to document the things a VM needs to provide to support the
function of the JDK, it suggests that currently the jvm.h in the /jdk
repo is the more appropriate to use for this purpose.

However, I recognise a tension here, as the information recorded is
potentially of most interest to VM developers (including those for
Hotspot), who are less likely to be paying attention to documentation
changes in a separate repo (that they may not even be cloning!).

This tension would be ameliorated once the two files become strict
duplicates.

Any thoughts or suggestions on better approaches to take on this would
be welcome.

Regards,
Neil

[1] http://en.wikipedia.org/wiki/Don%27t_repeat_yourself

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