linux-kernel - [PATCH] kernel-doc: restrict syntax for private: and public:

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: Windows password security audit tool. GUI, reports in PDF.

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

Message-Id: <20090428151757.0547392d.randy.dunlap@oracle.com>
Date:	Tue, 28 Apr 2009 15:17:57 -0700
From:	Randy Dunlap <randy.dunlap@...cle.com>
To:	lkml <linux-kernel@...r.kernel.org>
Cc:	akpm <akpm@...ux-foundation.org>, samr <sam@...nborg.org>
Subject: [PATCH] kernel-doc: restrict syntax for private: and public:

From: Randy Dunlap <randy.dunlap@...cle.com>

scripts/kernel-doc can (incorrectly) delete struct members that
are surrounded by /* ... */ <struct members> /* ... */
if there is a /* private: */ comment in there somewhere also.

Fix that by making the "/* private:" only allow whitespace
between /* and "private:", not anything/everything in the world.

This fixes some erroneous kernel-doc warnings that popped up
while processing include/linux/usb/composite.h.

Signed-off-by: Randy Dunlap <randy.dunlap@...cle.com>
---
 Documentation/kernel-doc-nano-HOWTO.txt |    7 +++++--
 scripts/kernel-doc                      |    7 ++++---
 2 files changed, 9 insertions(+), 5 deletions(-)

--- linux-2.6.30-rc3-git4.orig/scripts/kernel-doc
+++ linux-2.6.30-rc3-git4/scripts/kernel-doc
@@ -1411,7 +1411,8 @@ sub dump_struct($$) {
     my $file = shift;
     my $nested;
 
-    if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {
+    if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
+	#my $decl_type = $1;
 	$declaration_name = $2;
 	my $members = $3;
 
@@ -1420,8 +1421,8 @@ sub dump_struct($$) {
 	$nested = $1;
 
 	# ignore members marked private:
-	$members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;
-	$members =~ s/\/\*.*?private:.*//gos;
+	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
+	$members =~ s/\/\*\s*private:.*//gos;
 	# strip comments:
 	$members =~ s/\/\*.*?\*\///gos;
 	$nested =~ s/\/\*.*?\*\///gos;
--- linux-2.6.30-rc3-git4.orig/Documentation/kernel-doc-nano-HOWTO.txt
+++ linux-2.6.30-rc3-git4/Documentation/kernel-doc-nano-HOWTO.txt
@@ -269,7 +269,10 @@ Use the argument mechanism to document m
 
 Inside a struct description, you can use the "private:" and "public:"
 comment tags.  Structure fields that are inside a "private:" area
-are not listed in the generated output documentation.
+are not listed in the generated output documentation.  The "private:"
+and "public:" tags must begin immediately following a "/*" comment
+marker.  They may optionally include comments between the ":" and the
+ending "*/" marker.
 
 Example:
 
@@ -283,7 +286,7 @@ Example:
 struct my_struct {
     int a;
     int b;
-/* private: */
+/* private: internal use only */
     int c;
 };
 
--
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/