From mboxrd@z Thu Jan 1 00:00:00 1970 From: Avi Kivity Subject: Re: Patch to add doxygen documentation to KVM Date: Tue, 19 Dec 2006 16:54:57 +0200 Message-ID: <4587FD41.9010405@qumranet.com> References: Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Cc: kvm-devel-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org Return-path: To: James Jacobsson In-Reply-To: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: kvm-devel-bounces-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org Errors-To: kvm-devel-bounces-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org List-Id: kvm.vger.kernel.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