Re: [Qemu-devel] [Discussion 01/10] docs: add docs/api-hierarchy.txt

[Stefan Hajnoczi]

On Tue, Mar 04, 2014 at 05:58:13PM +0800, Xuebing wang wrote:
> 
> On 03/04/2014 05:42 PM, Stefan Hajnoczi wrote:
> >On Tue, Mar 04, 2014 at 10:47:21AM +0800, Xuebing Wang wrote:
> >>Signed-off-by: Xuebing Wang <address@hidden>
> >>---
> >>  docs/api-hierarchy.txt |   93 
> >> ++++++++++++++++++++++++++++++++++++++++++++++++
> >>  1 file changed, 93 insertions(+)
> >>  create mode 100644 docs/api-hierarchy.txt
> >This type of documentation gets outdated really quickly.  I'm not sure
> >it should be merged.
> >
> >Documenting the various APIs as doc comments in the code would have a
> >better chance of staying up-to-date.
> >
> 
> Thanks. But, doc comments in the code don't show the hierarchy and
> their dependencies (or inheriting relationship).
> 
> Any idea how to draw the hierarchy to show the big picture of the
> APIs (as a high-level API design doc)? :-)

We do have high-level documentation for specific modules.  For example,
see include/qom/object.h.  It documents more than just individual
functions.  So if you want to find out about QEMU Object Model, then
object.h has the documentation you need to get the big picture *and*
understand the APIs.

The relationships between modules are a different issue.  I don't think
it's worth trying to document them because they will get out of date.
What's worse than no documentation?  Incorrect documentation.

QEMU does not have a stable API, things can change at any time.  This
has many benefits but also the drawback that documentation gets outdated
quickly.  I don't think it's a good idea to give the impression that
things are stable when they are not.

In other words, module-level documentation is good but high-level API
design doesn't exist because we don't have a stable API.