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 <xbi...@gmail.com> > >>--- > >> 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.