Source-Changes-D archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

Re: CVS commit: src



At Sat, 27 Mar 2010 02:38:01 +1100, matthew green <mrg%eterna.com.au@localhost> 
wrote:
Subject: re: CVS commit: src
> 
> 
>    On Thu, 25 Mar 2010 16:57:16 +0000
>    Mindaugas Rasiukevicius <rmind%netbsd.org@localhost> wrote:
>    
>    > David Holland <dholland-sourcechanges%netbsd.org@localhost> wrote:
>    > >  > What Joerg said.  They are low level kernel implementation details.
>    > >  > These belong in a book or article or a wiki page or something, not 
> the
>    > >  > manual.
>    > > 
>    > > We just went around on this like two or three weeks ago on spl
>    > > internals. On the one hand, the man page should document the
>    > > interface, not the implementation; on the other hand, anything global
>    > > someone might run across while debugging or rototilling should be
>    > > documented. The resolution the last time was to document the internals
>    > > in a different man page. (And if we weren't out of man sections, it
>    > > would seem like a good section distinction: kernel interfaces
>    > > vs. kernel internals...)
>    > 
>    > First, I do not agree there was such resolution.
>    > 
>    > Second, what Joerg and Andrew said - these are implementation details
>    > and should rather be commented in the code (or internals doc, wiki, etc).
>    
>    Yes, we have wiki. Its exactly for this. Use it! :)
> 
> 
> documentation like *this* does not belong only in a wiki.  at
> the very least, it should be with the code, but i stand by my
> post yesterday -- this is about MI/MD interfaces and those
> belong in real manual pages.


Indeed!


(and personally I find wikis to be extremely poor collaboration tools,
but maybe I'm just too stuck in the old days! :-))

-- 
                                                Greg A. Woods
                                                Planix, Inc.

<woods%planix.com@localhost>       +1 416 218 0099        http://www.planix.com/

Attachment: pgph85YOLDB5Q.pgp
Description: PGP signature



Home | Main Index | Thread Index | Old Index