From owner-freebsd-chat@FreeBSD.ORG Mon Oct 12 17:03:08 2009 Return-Path: Delivered-To: chat@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 89897106568B for ; Mon, 12 Oct 2009 17:03:08 +0000 (UTC) (envelope-from reed@reedmedia.net) Received: from c-0500.emailmediator.com (c-0500.emailmediator.com [64.85.162.118]) by mx1.freebsd.org (Postfix) with ESMTP id 69E258FC0C for ; Mon, 12 Oct 2009 17:03:08 +0000 (UTC) Received: from pool-71-252-138-179.dllstx.fios.verizon.net ([71.252.138.179] helo=reedmedia.net) by c-0500.emailmediator.com with esmtpa (Exim 4.69) (envelope-from ) id 1MxOIe-00002b-ED for chat@freebsd.org; Mon, 12 Oct 2009 13:03:08 -0400 Received: from reed@reedmedia.net by reedmedia.net with local (mailout 0.17) id 11669-1255366989; Mon, 12 Oct 2009 12:03:09 -0500 Date: Mon, 12 Oct 2009 12:03:08 -0500 (CDT) From: "Jeremy C. Reed" X-X-Sender: reed@t1.m.reedmedia.net To: chat@freebsd.org Message-ID: User-Agent: Alpine 2.01 (NEB 1266 2009-07-14) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Cc: Subject: documenting code X-BeenThere: freebsd-chat@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Non technical items related to the community List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 12 Oct 2009 17:03:08 -0000 What do you use (tools or techniques) for documenting code for design decisions, code examples, history of API/ABI changes, graphical supplements (like design diagrams), etc? I'd like to generate both webpages that have full details plus manpages that have the synopsis, descriptions, return values, etc, but not all the design decisions nor images (of course) nor code examples which may be too long for a succinct manual page. I don't want to document in multiple places -- don't want to be redundant. I'd like to keep this documentation very near the code (even embedded) so when code is updated, it is easy to remember or do the documentation also. The code is mostly a mix of Python and C++. Do you use pydoc and/or doxygen? I see doxygen can insert images into the documentation, so could be used to insert design diagrams. And doxygen has conditional \if and \ifnot for conditionally showing or not showing documentation (which could be used for manpages versus complete HTML). I don't see image or manual page support for pydoc. If you have any examples (original documentation and rendered results in HTML and man), please let me know. Also if you have any developer guidelines that include documentation guidelines, please let me know.