This is the "spec" vs "guide" arguement.

On the "spec" side, the argument goes something like this:
         "The man pages are the specification for the system, by making them
          exhaustively complete one can insure compliance through testing to
          the agreed upon standard. This aids interoperability and 
compatibility
          amongst different implementations."

On the "guide" side, the argument goes something like this:
         "The man pages are a guide for the programmer who is using the
          system. They help him or her to write programs that will run
          under the system and identify the most common error conditions
          that might prevent the program from running. For really
          complex errors the source is always available."

Having had some experience at Sun on the "spec" side of the argument I can 
assure you that the NetBSD project doesn't have nearly enough resources to 
maintain a NetBSD specification. Therefore, unless you can do this for all 
man pages (ie spec mode) then it will be no better than guide mode, thus 
I'm going to suggest that the answer is guide mode.

In that mode it is important to cover the error conditions that are most 
likely to occur and to reference the definitive documentation (ie the 
source). So perhaps a good compromise would be a new MAN section 
"IMPLEMENTED IN" which identifies where in the source tree you can find the 
function.

--Chuck
At 10:57 AM 7/15/00 -0700, Erik E. Fair wrote:
>The PR wants every error that a given system call can return in the man 
>page for that system call (in section 2). I'm asking for discussion here 
>as to whether that's reasonable (it is gonna be a maintenance headache, 
>unless we find some automated way to produce it from the code paths).
>
>         Erik <fair@clock.org>