lkml.org 
[lkml]   [2009]   [Dec]   [23]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
Date
From
Subject[PATCH] documentation: update kernel-doc-nano-HOWTO information
From: Randy Dunlap <randy.dunlap@oracle.com>

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 <randy.dunlap@oracle.com>
---
Documentation/kernel-doc-nano-HOWTO.txt | 12 +++++++-----
1 file changed, 7 insertions(+), 5 deletions(-)

--- linux-2.6.33-rc1-git3.orig/Documentation/kernel-doc-nano-HOWTO.txt
+++ linux-2.6.33-rc1-git3/Documentation/kernel-doc-nano-HOWTO.txt
@@ -214,11 +214,13 @@ 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). 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!

\
 
 \ /
  Last update: 2009-12-23 18:55    [W:0.031 / U:0.536 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site