Re: Must check what?

[Andrew Morton <akpm@osdl.org>]

On Wed, 4 Oct 2006 12:37:53 -0600
Matthew Wilcox <matthew@wil.cx> wrote:

> 
> I'd like to propose that anyone adding __must_check markers in the
> future be forced to *WRITE SOME FUCKING DOCUMENTATION* about exactly
> what it is the caller is supposed to be checking.
> 
> extern int __must_check bus_register(struct bus_type * bus);
> 

I blame kernel-doc.  It should have a slot for documenting the return value,
but it doesn't, so nobody documents return values.

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.

> Why, thank you.  Does it return 0 for success, or 1 on success?  Does it
> return an errno?

yes, no, yes ;)