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>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200103162035.f2GKZkZ73579>