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.