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.
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.