From owner-cvs-all@FreeBSD.ORG Sun Jul 27 13:48:41 2003 Return-Path: Delivered-To: cvs-all@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 66FA237B401; Sun, 27 Jul 2003 13:48:41 -0700 (PDT) Received: from hermes.aueb.gr (hermes.aueb.gr [195.251.255.142]) by mx1.FreeBSD.org (Postfix) with ESMTP id A29A043F85; Sun, 27 Jul 2003 13:48:39 -0700 (PDT) (envelope-from dds@aueb.gr) Received: from aueb.gr (faculty07.right.dialup.aueb.gr [195.251.255.251]) by hermes.aueb.gr (8.12.9/8.12.9) with ESMTP id h6RKmGoj017102; Sun, 27 Jul 2003 23:48:16 +0300 Message-ID: <3F243888.784795AC@aueb.gr> Date: Sun, 27 Jul 2003 23:39:36 +0300 From: Diomidis Spinellis Organization: Athens University of Ecomomics and Business X-Mailer: Mozilla 4.78 [en] (Windows NT 5.0; U) X-Accept-Language: en,el,de MIME-Version: 1.0 To: Poul-Henning Kamp References: <65725.1059336010@critter.freebsd.dk> Content-Type: text/plain; charset=iso-8859-7 Content-Transfer-Encoding: 7bit cc: Alexander Leidinger cc: src-committers@FreeBSD.org cc: cvs-all@FreeBSD.org cc: cvs-src@FreeBSD.org Subject: Re: cvs commit: src/sys/kern init_main.c kern_malloc.c md5c.c subr_autoconf.c subr_mbuf.c subr_prf.c tty_subr.c vfs_cluster.c vfs_subr.c X-BeenThere: cvs-all@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: CVS commit messages for the entire tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 27 Jul 2003 20:48:41 -0000 Poul-Henning Kamp wrote: > The thing which grinds in my ear about most of the tools I have ever > heard about is "specially annotated source code" or "model reflecting > the structure of the program" and similar. > > I personally don't want to have to express the same ting multiple > times, once for the compiler and once for each interested tool is > N-1 times too many. There are often hidden opportunities to avoid this problem. As an example, our section 2 manual pages document the error codes of each system call using the .Er macro. I find this type of documentation extremely valuable; when I get a strange error from a system call I can grep for the errno value in /sys to see what is going on. The lists are not complete; I have in the last year corrected two manual pages where a given return code was missing. I could write a tool to follow the call graph, locate all "errno = " assignments for each function call, and compare them against the corresponding manual page. As I see it, the main obstacle is the various vtables that make the static establishment of the call graph a lot more difficult. Note that FreeBSD is uniquely positioned to capitalize on this opportinity: consider that the Win32 SDK does not even document the possible errors a system call can generate and we are using a special macro for tagging the errno values in our documentation. Diomidis - http://www.spinellis.gr