Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question)

[Stefan Hajnoczi <stefanha@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4344 bytes --]

On Tue, Nov 08, 2016 at 11:24:21AM -0500, John Snow wrote:
> 
> 
> On 11/08/2016 11:20 AM, Stefan Hajnoczi wrote:
> > On Mon, Nov 07, 2016 at 05:52:37PM -0500, John Snow wrote:
> > > On 11/07/2016 08:30 AM, Stefan Hajnoczi wrote:
> > > > On Sat, Nov 05, 2016 at 06:42:23PM +0000, Peter Maydell wrote:
> > > > > In particular I think we could:
> > > > >  * set up a framework for our in-tree docs/ which gives us a
> > > > >    place to put new docs (both for-users and for-developers) --
> > > > >    I think having someplace to put things will reduce the barrier
> > > > >    to people writing useful new docs
> > > > >  * gradually convert the existing docs to rst
> > > > >  * use the sphinx extension features to pull in the doc-comments
> > > > >    we have been fairly consistently writing over the last few years
> > > > >    (for instance a converted version of docs/memory.txt could pull
> > > > >    in doc comments from memory.h; or we can just write simple
> > > > >    wrapper files like a "Bitmap operations" document that
> > > > >    displays the doc comments from bitops.h)
> > > > 
> > > > You are suggesting Sphinx for two different purposes:
> > > > 
> > > > 1. Formatting docs/ in HTML, PDF, etc.
> > > > 
> > > > 2. API documentation from doc comments.
> > > > 
> > > > It's a good idea for #1 since we can then publish automated builds of
> > > > the docs.  They will be easy to view and link to in a web browser.
> > > > 
> > > > I'm not a fan of #2.  QEMU is not a C library that people develop
> > > > against and our APIs are not stable.  There is no incentive for pretty
> > > > doc comments.  It might be cool to set it up once but things will
> > > > deterioate again quickly because we don't actually need external API
> > > > docs.
> > > > 
> > > > Instead of #2 we should focus on generating nice external QMP docs for
> > > > libvirt and other clients.  That has a clear benefit.
> > > > 
> > > > Stefan
> > > > 
> > > 
> > > I think that designating certain interfaces within QEMU as "Internal API"
> > > has some merit and are worth documenting for the sake of device/format
> > > authors like Peter suggests.
> > 
> > To be clear, I'm not saying QEMU doesn't need doc comments.  Every new
> > function in include/*.h must have doc comments and many .c internal
> > functions should too.
> > 
> > I'm just not enthusiastic about an effort to reformat doc comments and
> > make them render to HTML, PDF, etc in a nice way because I don't think
> > there's much payoff from doing that or maintaining it.
> > 
> 
> OK, understood -- but if we are using a tool to syntax check the comment
> formats, which helps us keep consistency and our docs up to date, we get the
> PDF/html outputs "for free."
> 
> I agree they're not particularly useful, but I consider them a harmless side
> effect. They might also help prove to new contributors that we're serious
> about making QEMU easier to contribute to.
> 
> > > I think at a minimum, having _A_ standard approach cannot possibly be *any*
> > > worse than _NO_ standard approach.
> > 
> > People don't follow the standard format and markup syntax since that
> > requires rendering and checking that the HTML, PDF, etc output looks
> > correct before submitting patches.
> > 
> 
> My only experience is with Doxygen, but that at least does have warnings for
> a great number of things. As long as you're passing the generation checks, I
> think there's not much need to actually check the html/pdf outputs except
> periodically.
> 
> > I guess one solution is to extend checkpatch.pl to enforce that all doc
> > comments follow a standard format.  It still cannot check that @, #, etc
> > are used in the right places but at least it can make sure that some
> > standard layout is followed.
> > 
> 
> This is the part that I'm hoping the generation tool can fulfill, assuming
> it has generation warnings like Doxygen does.

If we can check that new functions have doc comments and the comments
follow the right format, then I'm happy.

No doc comments -> error.  Comments but not in doc format -> error.

The check needs to be run before submitting patches and also by patchew.
Otherwise those people who don't run the doc generator can fly under the
radar ;-).

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]