From owner-freebsd-arch Fri Mar 16 12:35:49 2001 Delivered-To: freebsd-arch@freebsd.org Received: from earth.backplane.com (earth-nat-cw.backplane.com [208.161.114.67]) by hub.freebsd.org (Postfix) with ESMTP id B9EF637B718; Fri, 16 Mar 2001 12:35:47 -0800 (PST) (envelope-from dillon@earth.backplane.com) Received: (from dillon@localhost) by earth.backplane.com (8.11.2/8.9.3) id f2GKZkZ73579; Fri, 16 Mar 2001 12:35:46 -0800 (PST) (envelope-from dillon) Date: Fri, 16 Mar 2001 12:35:46 -0800 (PST) From: Matt Dillon Message-Id: <200103162035.f2GKZkZ73579@earth.backplane.com> To: John Baldwin Cc: arch@FreeBSD.org Subject: Re: Proposal for the CPU interrupt API References: Sender: owner-freebsd-arch@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG Just to be clear. I am not advocating that everyone drop everything and start writing man pages... man pages take a lot of effort. But I would recommend that the procedures in the source code itself be documented in comments above each procedure whenever you have the chance and some time. That is ultimately the best way to document kernel interfaces, because it doesn't result in the documentation becoming outdated (whereas manual pages, while great and all that, tend to become outdated especially when things are changing quickly). The best examples of this sort of documentation in our current kernel is in vm/vm_page.h, vm/vm_page.c, and vm/vm_object.c. Alan, Alfred, I, DG, and others have had very good success keeping our understanding of the various functions in-sync and not stepping on each other's feet by keeping the documentation of the procedures up to date. kern/vfs_bio.c also is a good example of procedural documentation. -Matt To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-arch" in the body of the message