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

[Peter Maydell]

On 7 November 2016 at 13:30, Stefan Hajnoczi <address@hidden> wrote:
> 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.

I think my main argument here is that although it's fine
for experienced developers to go wading through the header
files for information, it's a bit of a wall for people who
are new to QEMU and have no idea what kinds of APIs we have
or which headers they might be in. We do see people appearing
on the mailing lists who'd like to add a device model or whatever
to QEMU and have no idea where to start or what the APIs they
need to use for it do. I'd like it to be easier for people to
get started with QEMU development.

A lot of docs/ is also internal technical documentation, which
you could argue equally tends to become out of date. I think
having the two integrated helps: the general overview info
can then link to or include the specifics on the functions.

Actually doing something with our docs comments would mean that
we notice things like "you changed this function but forgot
to update the docs with the new parameter" because they'd
generate a build error. I think it's lack of any automated
process of checking the doc comments that means they've
deteriorated.

thanks
-- PMM