Date: Fri, 16 Mar 2001 12:35:46 -0800 (PST) From: Matt Dillon <dillon@earth.backplane.com> To: John Baldwin <jhb@FreeBSD.org> Cc: arch@FreeBSD.org Subject: Re: Proposal for the CPU interrupt API Message-ID: <200103162035.f2GKZkZ73579@earth.backplane.com> References: <XFMail.010316122152.jhb@FreeBSD.org>
index | next in thread | previous in thread | raw e-mail
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 messagehome | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200103162035.f2GKZkZ73579>