From owner-freebsd-arch Fri Mar 16 13:20:18 2001 Delivered-To: freebsd-arch@freebsd.org Received: from gndrsh.dnsmgr.net (GndRsh.dnsmgr.net [198.145.92.4]) by hub.freebsd.org (Postfix) with ESMTP id CB9D037B718; Fri, 16 Mar 2001 13:20:14 -0800 (PST) (envelope-from freebsd@gndrsh.dnsmgr.net) Received: (from freebsd@localhost) by gndrsh.dnsmgr.net (8.9.3/8.9.3) id NAA54727; Fri, 16 Mar 2001 13:20:06 -0800 (PST) (envelope-from freebsd) From: "Rodney W. Grimes" Message-Id: <200103162120.NAA54727@gndrsh.dnsmgr.net> Subject: Re: Proposal for the CPU interrupt API In-Reply-To: <200103162035.f2GKZkZ73579@earth.backplane.com> from Matt Dillon at "Mar 16, 2001 12:35:46 pm" To: dillon@earth.backplane.com (Matt Dillon) Date: Fri, 16 Mar 2001 13:20:06 -0800 (PST) Cc: jhb@FreeBSD.ORG (John Baldwin), arch@FreeBSD.ORG X-Mailer: ELM [version 2.4ME+ PL54 (25)] MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: owner-freebsd-arch@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG > 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). 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 To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-arch" in the body of the message