re: CVS commit: src

[matthew green <mrg%eterna.com.au@localhost>]

   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.
   

.mrg.