[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format questio
From: |
Daniel P. Berrange |
Subject: |
Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question) |
Date: |
Mon, 7 Nov 2016 13:41:55 +0000 |
User-agent: |
Mutt/1.7.1 (2016-10-04) |
On Mon, Nov 07, 2016 at 01:30:45PM +0000, 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.
For shared internal infrastructure code I very much disagree. If I'm
writing something (like a new block driver), I'm relying on a bunch
of existing code that I'm calling. Some of the methods I'm consuming
may be in a library like GLib, other methods may be QEMU internal
infrastructure (like util/*, io/*, cryto/*). Regardless of whether
those methods are internal or from a library, the API docs are very
important / valuable in ensuring I'm understanding the required usage
contract of the method. The lack of API docs for the QEMU block layer
was a major cause of pain for me when writing the LUKS driver.
Regards,
Daniel
--
|: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org -o- http://virt-manager.org :|
|: http://entangle-photo.org -o- http://search.cpan.org/~danberr/ :|
- [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Peter Maydell, 2016/11/05
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Daniel P. Berrange, 2016/11/07
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Stefan Hajnoczi, 2016/11/07
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question),
Daniel P. Berrange <=
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Peter Maydell, 2016/11/07
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), John Snow, 2016/11/07
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Stefan Hajnoczi, 2016/11/08
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), John Snow, 2016/11/08
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Stefan Hajnoczi, 2016/11/09
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Fam Zheng, 2016/11/09
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Paolo Bonzini, 2016/11/10
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Daniel P. Berrange, 2016/11/10
- Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Stefan Hajnoczi, 2016/11/10
Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Paolo Bonzini, 2016/11/08