Re: Must check what?

[Matthew Wilcox <matthew@wil.cx>]

On Wed, Oct 04, 2006 at 12:02:42PM -0700, Andrew Morton wrote:
> I blame kernel-doc.  It should have a slot for documenting the return value,
> but it doesn't, so nobody documents return values.

There's also the question about where the documentation should go.  By
the function prototype in the header?  That's the easy place for people
using the function to find it.  By the code?  That's the place where it
stands the most chance (about 10%) of somebody bothering to update it
when they change the code.

> It should have a slot for documenting caller-provided locking requirements
> too.  And for permissible calling-contexts.  They're all part of the
> caller-provided environment, and these two tend to be a heck of a lot more
> subtle than the function's formal arguments.

Indeed.  And reference count assumptions.  It's almost like we want a
pre-condition assertion ...