From owner-freebsd-arch Fri Mar 16 13:38:30 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 3BE2F37B719; Fri, 16 Mar 2001 13:38:27 -0800 (PST) (envelope-from dillon@earth.backplane.com) Received: (from dillon@localhost) by earth.backplane.com (8.11.2/8.9.3) id f2GLc8d74959; Fri, 16 Mar 2001 13:38:08 -0800 (PST) (envelope-from dillon) Date: Fri, 16 Mar 2001 13:38:08 -0800 (PST) From: Matt Dillon Message-Id: <200103162138.f2GLc8d74959@earth.backplane.com> To: "Rodney W. Grimes" Cc: jhb@FreeBSD.ORG (John Baldwin), arch@FreeBSD.ORG Subject: Re: Proposal for the CPU interrupt API References: <200103162120.NAA54727@gndrsh.dnsmgr.net> Sender: owner-freebsd-arch@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG :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