Corrections please ...

Corrections please ...

[Kevin Diggs]

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

[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
@@ -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().
+ */
  struct completion {
         unsigned int done;
         wait_queue_head_t wait;
@@ -36,6 +46,13 @@
  # define DECLARE_COMPLETION_ONSTACK(work) DECLARE_COMPLETION(work)
  #endif

+/**
+ * init_completion: - Initialize a dynamically allocated completion
+ * @x:  completion structure that is to be initialized
+ *
+ * This inline function will initialize a dynamically created completion
+ * structure.
+ */
  static inline void init_completion(struct completion *x)
  {
         x->done = 0;


--- kernel/sched.c.orig 2008-08-13 02:22:42.000000000 -0700
+++ kernel/sched.c      2008-08-18 13:31:03.000000000 -0700
@@ -4363,6 +4363,13 @@
  }
  EXPORT_SYMBOL_GPL(__wake_up_sync);     /* For internal use only */

+/**
+ * complete: - signals a single thread waiting on this completion
+ * @x:  holds the state of this particular completion
+ *
+ * This will wake up a single thread waiting on this completion. If 
multiple
+ * threads are waiting ???
+ */
  void complete(struct completion *x)
  {
         unsigned long flags;
@@ -4374,6 +4381,12 @@
  }
  EXPORT_SYMBOL(complete);

+/**
+ * complete_all: - signals all threads waiting on this completion
+ * @x:  holds the state of this particular completion
+ *
+ * This will wake up all threads waiting on this particular completion 
event.
+ */
  void complete_all(struct completion *x)
  {
         unsigned long flags;
@@ -4425,12 +4438,27 @@
         return timeout;
  }

+/**
+ * wait_for_completion: - waits for completion of a task
+ * @x:  holds the state of this particular completion
+ *
+ * This waits to be signaled for completion of a specific task. It is NOT
+ * interruptible and there is no timeout.
+ */
  void __sched wait_for_completion(struct completion *x)
  {
         wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_UNINTERRUPTIBLE);
  }
  EXPORT_SYMBOL(wait_for_completion);

+/**
+ * wait_for_completion_timeout: - waits for completion of a task 
(w/timeout)
+ * @x:  holds the state of this particular completion
+ * @timeout:  timeout value in jiffies
+ *
+ * This waits to be signaled for completion of a specific task. It is NOT
+ * interruptible. But there is a timeout in jiffies.
+ */
  unsigned long __sched
  wait_for_completion_timeout(struct completion *x, unsigned long timeout)
  {
@@ -4438,6 +4466,13 @@
  }
  EXPORT_SYMBOL(wait_for_completion_timeout);

+/**
+ * wait_for_completion_interruptible: - waits for completion of a task 
(w/intr)
+ * @x:  holds the state of this particular completion
+ *
+ * This waits to be signaled for completion of a specific task. It is
+ * interruptible.
+ */
  int __sched wait_for_completion_interruptible(struct completion *x)
  {
         long t = wait_for_common(x, MAX_SCHEDULE_TIMEOUT, 
TASK_INTERRUPTIBLE);
@@ -4447,6 +4482,14 @@
  }
  EXPORT_SYMBOL(wait_for_completion_interruptible);

+/**
+ * wait_for_completion_interruptible_timeout: - waits for completion 
(w/(to,int
r))
+ * @x:  holds the state of this particular completion
+ * @timeout:  timeout value in jiffies
+ *
+ * This waits to be signaled for completion of a specific task. It is
+ * interruptible. And there is a timeout in jiffies.
+ */
  unsigned long __sched
  wait_for_completion_interruptible_timeout(struct completion *x,
                                           unsigned long timeout)
@@ -4455,6 +4498,13 @@
  }
  EXPORT_SYMBOL(wait_for_completion_interruptible_timeout);

+/**
+ * wait_for_completion_killable: - waits for completion of a task 
(killable)
+ * @x:  holds the state of this particular completion
+ *
+ * This waits to be signaled for completion of a specific task. It is
+ * killable (???).
+ */
  int __sched wait_for_completion_killable(struct completion *x)
  {
         long t = wait_for_common(x, MAX_SCHEDULE_TIMEOUT, TASK_KILLABLE);

Re: Corrections please ...

[Michael Ellerman]

[-- Attachment #1: Type: text/plain, Size: 415 bytes --]

On Mon, 2008-08-18 at 13:59 -0700, Kevin Diggs wrote:
> Could I get any needed corrections on this. Especially on the "???"

You're missing CC: lkml.

cheers

-- 
Michael Ellerman
OzLabs, IBM Australia Development Lab

wwweb: http://michael.ellerman.id.au
phone: +61 2 6212 1183 (tie line 70 21183)

We do not inherit the earth from our ancestors,
we borrow it from our children. - S.M.A.R.T Person

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Corrections please ...

[Arnd Bergmann]

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 <><