Re: [Qemu-devel] [PATCH v3 32/50] qapi2texi: add 'If:' section to generated documentation

[Eric Blake]

On 12/13/2017 06:35 AM, Markus Armbruster wrote:
> Cc: Eric for an additional pair of eyeballs.
> 
> Marc-André Lureau <address@hidden> writes:
> 
>> The documentation is generated only once, and doesn't know C
>> pre-conditions. Add 'If:' sections for top-level entities.
> 
> Is this what we want?
> 
> QMP also exists only once.  Should the generated qemu-qmp-ref.* document
> that instance of QMP, or should it document all potential instances of
> QMP?
> 

I can go either way; it's nice to know that the binary that this copy of
documentation was bundled with only understands these terms (the binary
was compiled without HAVE_FOO, so any code guarded by HAVE_FOO doesn't
need to be documented); but that limits the usability of that
documentation to just that binary.  It's also useful to have
fully-generic documentation hosted on the website, where everything is
documented (the documentation describes all possible builds of qemu
2.12, not just the one you installed), while mentioning the conditional
nature of the documented feature ("qemu in general knows about these
things; but check your particular binary by doing XYZ to learn if that
support was compiled in to your binary").

So having typed that, I think I'm leaning slightly towards documenting
everything, including conditionals, rather than trimming the document to
match the current build conditions.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

signature.asc
Description: OpenPGP digital signature