All of
 help / color / mirror / Atom feed
* - discuss-a-couple-common-errors-in-kernel-doc-usage.patch removed from -mm tree
@ 2007-02-11 22:53 akpm
  0 siblings, 0 replies; only message in thread
From: akpm @ 2007-02-11 22:53 UTC (permalink / raw)
  To: rpjday, randy.dunlap, mm-commits

The patch titled
     Discuss a couple common errors in kernel-doc usage.
has been removed from the -mm tree.  Its filename was

This patch was dropped because it was merged into mainline or a subsystem tree

Subject: Discuss a couple common errors in kernel-doc usage.
From: "Robert P. J. Day" <>

Explain a couple of the most common errors in kernel-doc usage.

Signed-off-by: Robert P. J. Day <>
Acked-by: Randy Dunlap <>
Signed-off-by: Andrew Morton <>

 Documentation/kernel-doc-nano-HOWTO.txt |   37 +++++++++++++++++++---
 1 file changed, 33 insertions(+), 4 deletions(-)

diff -puN Documentation/kernel-doc-nano-HOWTO.txt~discuss-a-couple-common-errors-in-kernel-doc-usage Documentation/kernel-doc-nano-HOWTO.txt
--- a/Documentation/kernel-doc-nano-HOWTO.txt~discuss-a-couple-common-errors-in-kernel-doc-usage
+++ a/Documentation/kernel-doc-nano-HOWTO.txt
@@ -107,10 +107,14 @@ The format of the block comment is like 
  * (section header: (section description)? )*
-The short function description cannot be multiline, but the other
-descriptions can be (and they can contain blank lines). Avoid putting a
-spurious blank line after the function name, or else the description will
-be repeated!
+The short function description ***cannot be multiline***, but the other
+descriptions can be (and they can contain blank lines).  If you continue
+that initial short description onto a second line, that second line will
+appear further down at the beginning of the description section, which is
+almost certainly not what you had in mind.
+Avoid putting a spurious blank line after the function name, or else the
+description will be repeated!
 All descriptive text is further processed, scanning for the following special
 patterns, which are highlighted appropriately.
@@ -121,6 +125,31 @@ patterns, which are highlighted appropri
 '@parameter' - name of a parameter
 '%CONST' - name of a constant.
+NOTE 1:  The multi-line descriptive text you provide does *not* recognize
+line breaks, so if you try to format some text nicely, as in:
+  Return codes
+    0 - cool
+    1 - invalid arg
+    2 - out of memory
+this will all run together and produce:
+  Return codes 0 - cool 1 - invalid arg 2 - out of memory
+NOTE 2:  If the descriptive text you provide has lines that begin with
+some phrase followed by a colon, each of those phrases will be taken as
+a new section heading, which means you should similarly try to avoid text
+  Return codes:
+    0: cool
+    1: invalid arg
+    2: out of memory
+every line of which would start a new section.  Again, probably not
+what you were after.
 Take a look around the source tree for examples.

Patches currently in -mm which might be from are


^ permalink raw reply	[flat|nested] only message in thread

only message in thread, other threads:[~2007-02-11 22:54 UTC | newest]

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2007-02-11 22:53 - discuss-a-couple-common-errors-in-kernel-doc-usage.patch removed from -mm tree akpm

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.