From owner-freebsd-arch  Fri Mar 16 20:22:15 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 C0EEF37B718; Fri, 16 Mar 2001 20:22:11 -0800 (PST)
	(envelope-from freebsd@gndrsh.dnsmgr.net)
Received: (from freebsd@localhost)
	by gndrsh.dnsmgr.net (8.9.3/8.9.3) id UAA55781;
	Fri, 16 Mar 2001 20:22:08 -0800 (PST)
	(envelope-from freebsd)
From: "Rodney W. Grimes" <freebsd@gndrsh.dnsmgr.net>
Message-Id: <200103170422.UAA55781@gndrsh.dnsmgr.net>
Subject: Re: Proposal for the CPU interrupt API
In-Reply-To: <200103162138.f2GLc8d74959@earth.backplane.com> from Matt Dillon at "Mar 16, 2001 01:38:08 pm"
To: dillon@earth.backplane.com (Matt Dillon)
Date: Fri, 16 Mar 2001 20:22:07 -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

> :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).
                  ^^^^^^^^^^^^^^^^^^^^^^^

and by otherwise I included comments in code.  Take this one for example:
From sys/i386/isa/if_sr.c
        /*
         * XXX Disable all interrupts for now. I think if you are using the
         * dmac you don't use these interrupts.
         */
        SRC_PUT8(hc->sca_base, msci->ie0, 0);
        SRC_PUT8(hc->sca_base, msci->ie1, 0x0C);

writting 0x0C to msci->ie1 does NOT disable all interrupts!!!

> :
> :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
> 
> 


-- 
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