Date: Wed, 4 Oct 2006 13:25:37 -0600
From: Matthew Wilcox <matthew@wil.cx>
To: Andrew Morton <akpm@osdl.org>
Cc: linux-kernel@vger.kernel.org
Subject: Re: Must check what?
Message-ID: <20061004192537.GH28596@parisc-linux.org>
References: <20061004183752.GG28596@parisc-linux.org> <20061004120242.319a47e4.akpm@osdl.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20061004120242.319a47e4.akpm@osdl.org>
User-Agent: Mutt/1.5.13 (2006-08-11)
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 1124
Lines: 22

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 ...
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/