Date: Fri, 16 Mar 2001 13:38:08 -0800 (PST) From: Matt Dillon <dillon@earth.backplane.com> To: "Rodney W. Grimes" <freebsd@gndrsh.dnsmgr.net> Cc: jhb@FreeBSD.ORG (John Baldwin), arch@FreeBSD.ORG Subject: Re: Proposal for the CPU interrupt API Message-ID: <200103162138.f2GLc8d74959@earth.backplane.com> References: <200103162120.NAA54727@gndrsh.dnsmgr.net>
next in thread | previous in thread | raw e-mail | index | archive | help
:Every committer should be slapped on the hand every time they make a
:commit that changes source code that does not update the related
:documentation (man page or otherwise).
:
:5 slapps on the hand and a commit bit should be suspended. Three
:suspensions and it should be revoked.
:
:The excuse that they don't know how to deal with nroff and mandoc is
:not really acceptable. They can always inlist the help of those that
:do understand these things, and hold the commit until both parts are
:ready.
:
:Rod Grimes - KD7CAX @ CN85sl - (RWG25) rgrimes@gndrsh.dnsmgr.net
Well, the problem is that only 1% of the kernel interfaces are
documented with man pages. So if you are requiring every single committer
working on the kernel to go and check to see if a man 9 section exists
for some of the dozens of files they just touched, well, I'm afraid that
is a bit over the top. FreeBSD's committers have historically *NOT*
done that, so depending on it now is a bad idea. It just won't happen.
This isn't to say that man 9 pages are useless... but I would say that
they are not as useful in an environment that is changing as quickly
as -current is. On the otherhand, documenting the procedures in the
source itself is a whole lot easier for the committers to do. It
represents a relatively small burden instead of a large one, which means
that the source code comments wind up being more up to date and more
complete.
-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?200103162138.f2GLc8d74959>