kernel-doc: restrict syntax for private: and public:
PATCH 1/1 kernel-doc: restrict syntax for private: and public:
From: Randy Dunlap <[email protected]>
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.
--- Documentation/kernel-doc-nano-HOWTO.txt | 7 +++++-- scripts/kernel-doc | 7 ++++--- 2 files changed, 9 insertions(+), 5 deletions(-)
scripts/kernel-doc +4 -3
@@ -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;
Documentation/kernel-doc-nano-HOWTO.txt +5 -2
@@ -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; };
Quoted 11 lines · Randy Dunlap
From: Randy Dunlap <[email protected]>
scripts/kernel-doccan (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.
Applied to kbuild-next.
Sam