From owner-freebsd-current@FreeBSD.ORG Sun May 1 16:21:26 2005 Return-Path: Delivered-To: freebsd-current@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 07A2F16A4CE for ; Sun, 1 May 2005 16:21:26 +0000 (GMT) Received: from mailout06.sul.t-online.com (mailout06.sul.t-online.com [194.25.134.19]) by mx1.FreeBSD.org (Postfix) with ESMTP id 210DA43D3F for ; Sun, 1 May 2005 16:21:25 +0000 (GMT) (envelope-from Alexander@Leidinger.net) Received: from fwd23.aul.t-online.de by mailout06.sul.t-online.com with smtp id 1DSHC7-00085G-03; Sun, 01 May 2005 18:21:23 +0200 Received: from Andro-Beta.Leidinger.net (Zk3Y+qZ-ge1z-HkFtUoZW8Zt4u4WKr4bi5I9bMvfvF+wNUFQrLxxgo@[217.83.26.1]) by fwd23.sul.t-online.de with esmtp id 1DSHC0-0f90iG0; Sun, 1 May 2005 18:21:16 +0200 Received: from Magellan.Leidinger.net (Magellan.Leidinger.net [192.168.1.1]) j41GLFxZ096325; Sun, 1 May 2005 18:21:15 +0200 (CEST) (envelope-from Alexander@Leidinger.net) Date: Sun, 1 May 2005 18:22:01 +0200 From: Alexander Leidinger To: "Poul-Henning Kamp" , current@freebsd.org Message-ID: <20050501182201.170de4c7@Magellan.Leidinger.net> In-Reply-To: <11870.1114963192@critter.freebsd.dk> References: <20050501170800.1bf7e377@Magellan.Leidinger.net> <11870.1114963192@critter.freebsd.dk> X-Mailer: Sylpheed-Claws 1.0.4 (GTK+ 1.2.10; i386-portbld-freebsd6.0) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-ID: Zk3Y+qZ-ge1z-HkFtUoZW8Zt4u4WKr4bi5I9bMvfvF+wNUFQrLxxgo@t-dialin.net X-TOI-MSGID: bb37cffc-2217-4e01-8f9b-dfb7ce4afc33 Subject: Re: Doxygen generated PDF's of parts of the kernel available X-BeenThere: freebsd-current@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Discussions about the use of FreeBSD-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 01 May 2005 16:21:26 -0000 On Sun, 01 May 2005 17:59:52 +0200 "Poul-Henning Kamp" wrote: > As far as I can tell, this gives us very little over a normal > code reading because we have not marked up our source code. Yes. > If we mark up the source code for doxygen, does that buy us anything > besides more text in the pdf files ? The answer depends upon what you think about a good API (or better: KPI, Kernel Programming Interface) documentation. > Or to put the question another way: Is the doxygen markup > *semantically* useful for any automated code-munching tools ? I don't know such a tool. > Will anything tell us "you have an inconsistency here" or "this is > ambiguous" etc ? Doxygen can tell us: "this isn't documented" or "the dependency/call graph looks like ". > It's not that I am against marking up for doxygen, that is probably > a good idea at some level. It integrates the documentation with the source. It's detectable if you change the number of parameters but forget to document it. It allows to follow inter-file code flow faster than just by using less or something like this. > My primary interest is tools which will tell us something about our > source code which we didn't know before, not just pretty-print what > we told it ourselves. If you have tools or an IDE which tells you what the dependency/call graph looks like, doxygen most likely doesn't fits your needs. Bye, Alexander. -- Speak softly and carry a cellular phone. http://www.Leidinger.net Alexander @ Leidinger.net GPG fingerprint = C518 BC70 E67F 143F BE91 3365 79E2 9C60 B006 3FE7