Date: Fri, 16 Mar 2001 20:22:07 -0800 (PST) From: "Rodney W. Grimes" <freebsd@gndrsh.dnsmgr.net> To: dillon@earth.backplane.com (Matt Dillon) Cc: jhb@FreeBSD.ORG (John Baldwin), arch@FreeBSD.ORG Subject: Re: Proposal for the CPU interrupt API Message-ID: <200103170422.UAA55781@gndrsh.dnsmgr.net> In-Reply-To: <200103162138.f2GLc8d74959@earth.backplane.com> from Matt Dillon at "Mar 16, 2001 01:38:08 pm"
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).
^^^^^^^^^^^^^^^^^^^^^^^
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200103170422.UAA55781>