On 7 November 2016 at 13:30, Stefan Hajnoczi <stefa...@gmail.com> 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
