From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:41519) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WKnyu-00030c-9R for qemu-devel@nongnu.org; Tue, 04 Mar 2014 06:58:02 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WKnyo-00068U-9T for qemu-devel@nongnu.org; Tue, 04 Mar 2014 06:57:56 -0500 Received: from mx1.redhat.com ([209.132.183.28]:39279) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WKnyo-00068N-18 for qemu-devel@nongnu.org; Tue, 04 Mar 2014 06:57:50 -0500 Date: Tue, 4 Mar 2014 12:57:45 +0100 From: Stefan Hajnoczi Message-ID: <20140304115745.GA29749@stefanha-thinkpad.redhat.com> References: <1393901250-3922-1-git-send-email-xbing6@gmail.com> <1393901250-3922-2-git-send-email-xbing6@gmail.com> <20140304094244.GH25676@stefanha-thinkpad.redhat.com> <5315A3B5.4040805@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <5315A3B5.4040805@gmail.com> Subject: Re: [Qemu-devel] [Discussion 01/10] docs: add docs/api-hierarchy.txt List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Xuebing wang Cc: Stefan Hajnoczi , qemu-devel@nongnu.org, afaerber@suse.de, pbonzini@redhat.com 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 > >>--- > >> 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.