|author||Randy Dunlap <email@example.com>||2010-01-08 14:43:09 -0800|
|committer||Linus Torvalds <firstname.lastname@example.org>||2010-01-11 09:34:07 -0800|
documentation: update kernel-doc-nano-HOWTO information
Remove comments about function short descriptions not allowed to be on multiple lines (that was fixed/changed recently). Add comments that function "section header:" names need to be unique per function/struct/union/typedef/enum. Signed-off-by: Randy Dunlap <email@example.com> Signed-off-by: Andrew Morton <firstname.lastname@example.org> Signed-off-by: Linus Torvalds <email@example.com>
Diffstat (limited to 'Documentation')
1 files changed, 7 insertions, 5 deletions
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt
index 348b9e5e28f..27a52b35d55 100644
@@ -214,11 +214,13 @@ The format of the block comment is like this:
* (section header: (section description)? )*
-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.
+All "description" text can span multiple lines, although the
+function_name & its short description are traditionally on a single line.
+Description text may also contain blank lines (i.e., lines that contain
+only a "*").
+"section header:" names must be unique per function (or struct,
+union, typedef, enum).
Avoid putting a spurious blank line after the function name, or else the
description will be repeated!