Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 52dc5aec authored by Randy Dunlap's avatar Randy Dunlap Committed by Linus Torvalds
Browse files

kernel-doc: restrict syntax for private: and public: 



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: default avatarRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 00a62ce9

Documentation/kernel-doc-nano-HOWTO.txt

+5 −2
Original line number Diff line number Diff line
@@ -269,7 +269,10 @@ Use the argument mechanism to document members or constants. 


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;

};

scripts/kernel-doc

+4 −3
Original line number Diff line number Diff line
@@ -1412,6 +1412,7 @@ sub dump_struct($$) { 
    my $nested;



    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;