In some email I received from xs@kittenz.org, sie wrote:
> on Sat, Jun 15, 2002 at 03:23:11PM +1000, Darren Reed wrote:
> > - statement about which locks are expected to be held and how.
> ....
> > - statement about which interrupts are expected to be masked or not.
> ....
> > - statement about what the function does, including what is considered
> 
> Isn't a section 9 manual page a good place to put this kind of thing?
> Under .Sh LOCKS or some such.
> Obviously not every function needs a man page, but since there are so
> many functions and structures documented in this way already, it means
> there's less work. It's also less of an eye sore for those that do not
> wish to see it.

No, man pages are not the right place to put this kind of information.

This needs to be *with* the source code so that when you're working on
it the information is *there*, not somewhere else.

Darren