> 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).

There has been some inconclusive discussion in the past with respect
to documenting errors listed in the standards that we don't/can't
return.

I would like to see the project's policy on this documented somewhere,
once it is decided.  (Assuming that at least -core can come to some
consensus, even if the general mailing lists can't. :-)

So that I'm not sitting on the fence, I think:

1. all known error returns should be documented
2. all error returns listed in the standards should be documented
   ("which" standards?  Um ...)

I would treat #1 as a goal and update manual pages as and when someone
notices an omission or extraneous listing.  #2 is easy enough to do
for any standard for which an online copy is available.

I'm a bit dubious that an automated check of the source tree will be
able to do the right thing for #1, since functions called through
pointers will be hard to manage.  Not to mention system calls that can
use functionality provided by LKMs ... anything is possible for those.

Regards,

Giles