linux-kernel - [PATCH] documentation: update kernel-doc-nano-HOWTO information

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [day] [month] [year] [list]

Message-Id: <20091223094923.44266893.randy.dunlap@oracle.com>
Date:	Wed, 23 Dec 2009 09:49:23 -0800
From:	Randy Dunlap <randy.dunlap@...cle.com>
To:	lkml <linux-kernel@...r.kernel.org>
Cc:	akpm <akpm@...ux-foundation.org>
Subject: [PATCH] documentation: update kernel-doc-nano-HOWTO information

From: Randy Dunlap <randy.dunlap@...cle.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@...cle.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!
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/