Re: Patch to add doxygen documentation to KVM

[Avi Kivity <avi-atKUWr5tajBWk0Htik3J/w@public.gmane.org>]

James Jacobsson wrote:
> Attached is a patch to add some API documentation for libkvm to the
> source-tree (applies to the trunk).
> Also attached is the Doxyfile and a separate document which I use to
> generate documentation on my machine, just for reference.
>
> This is the first suggestion of how we could have our documentation,
> so it's nowhere near complete, although it covers many of the libkvm
> functions already.
>
> I'd appreciate any feedback you could give me on the documentation,
> such as if it is verbose enough, is it accurate, etc.
>

First, great job.

Second, please tell your mailer to set the content disposition of 
attachments to "inline".  This allows easy review and feedback.

Some concrete feedback:

- wrap lines at 80 characters
- documenting the registers is a bit too verbose.  VMM authors are 
expected to know such things.
- the documentation for kvm_inject_irq() is incorrect - the input is not 
a bitmask, but a vector number.  The processor does not have 256 
interrupt pins.  You can say something along the lines of "simulate an 
external vectored interrupt".
- kvm_run() also returns on a signal (EINTR), which is not an error.  
Signals are the primary method of simulating external interrupts and 
timers, and for implementing I/O completions.
- kvm_run() should explicitly state (it is only implied now) that it 
will call functions in the callback vector.
- the patch should contain changes to user/Makefile so that 'make doc' 
there will generate the documentation.  Please put all files into the 
patch ('diff -N')

-- 
error compiling committee.c: too many arguments to function


-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV