Date: Wed, 20 Aug 2008 11:52:44 +1000
From: Dave Chinner <david@fromorbit.com>
To: Kevin Diggs <kevdig@hypersurf.com>
Cc: linux-kernel@vger.kernel.org, stefanr@s5r6.in-berlin.de, arnd@arndb.de
Subject: Re: {NOT a PATCH} Corrections please ...
Message-ID: <20080820015244.GA6061@disturbed>
Mail-Followup-To: Kevin Diggs <kevdig@hypersurf.com>,
	linux-kernel@vger.kernel.org, stefanr@s5r6.in-berlin.de,
	arnd@arndb.de
References: <48AB73A3.9010404@hypersurf.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <48AB73A3.9010404@hypersurf.com>
User-Agent: Mutt/1.5.18 (2008-05-17)
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 1049
Lines: 28

On Tue, Aug 19, 2008 at 06:30:11PM -0700, Kevin Diggs wrote:
> Hi,
>
> 	It was recommended that I use a completion in a driver I am working on.  
> While figuring out how to use one, I noticed that there was no kernel  
> doc block comments. I am trying to add them. I would rather not have to  
> respin the patch for corrections.

Rather than documenting exactly how the queuing and wakeup occurs on
all functions, you should document it once. i.e. that completions
currently use FIFO queuing. It is probably best to do this at the
definition of the struct completion.

The reason is that if the implementation changes (e.g. to support
priorities and inheritence) the comments are then incorrect and
then there's lots of comments to remove^Wchange.

Cheers,

Dave.
-- 
Dave Chinner
david@fromorbit.com
--
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/