Re: Corrections please ...

[Arnd Bergmann <arnd@arndb.de>]

On Monday 18 August 2008, Kevin Diggs wrote:
> Subject: Corrections please ...

The subject should be the one line change log, e.g.

[PATCH] add kerneldoc comments for completion.h

Also, cc the maintainer of the code. If you can't tell
from the MAINTAINERS file, look for the most common
name when doing 'git log path/to/file.c'. In this case,
there does not seem to be an actual maintainer, but I
would expect Willy and Ingo to be interested in the code.

Read Documentation/SubmittingPatches.

> Could I get any needed corrections on this. Especially on the "???"
> 

The introductory text should explain why the patch is needed.
If you have more comments, put them behind the changelog text,
under a '---' line.

> [kevdig@PowerMac8600B linux-2.6.26]$ diff -U3 
> include/linux/completion.{h.orig,h}|more
> --- include/linux/completion.h.orig     2008-08-13 00:56:52.000000000 -0700
> +++ include/linux/completion.h  2008-08-18 13:00:23.000000000 -0700

Patches should be in -p1 format. Best use a tool like quilt, git or
mercurial to generate the patch instead of doing it by hand.

> @@ -10,6 +10,16 @@
> 
>   #include <linux/wait.h>
> 
> +/**
> + * struct completion - structure used to maintain state for a "completion"
> + * @done:  counting variable used to signal completion
> + * @wait:  internal wait queue head; used for locking and synchronization
> + *
> + * This is the structure used to maintain the state for a "completion". See
> + * also:  complete(), wait_for_completion() (and friends _timeout,
> + * _interruptible, _interruptible_timeout, and _killable), 
> init_completion(),
> + * and macros DECLARE_COMPLETION() and INIT_COMPLETION().
> + */

Line wrapping is broken, you need the right settings for sending unmodified
emails from your mail client.

	Arnd <><