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>