kernel-doc: Fix stripping of #define in enums

kernel-doc: Fix stripping of #define in enums

[conchur]

From: Conchúr Navid <conchur@web.de>

The regex to strip single line #define's in enumerations depends on the
fact that the defines are still stored on separate lines. But the
surrounding code already removed newlines and replaced them with
semicolons.

For example a simple input like

    /**
     * enum flags - test flags
     * @flag1: first flag
     * @flag2: second flag
     * @flag3: third flag
     * @flag4: fourth flag
     */
    enum flags {
    	flag1 = BIT(0),
    	flag2 = BIT(1),
    #define flags_small (flag1 | flag2)
    	flag3 = BIT(2),
    	flag4 = BIT(3),
    #define flags_big (flag2 | flag3)
    };

resulted in parsing warnings like

    warning: Enum value '#define flags_small (flag1 | flag2);flag3 = BIT(2)' not described in enum 'flags'
    warning: Enum value '#define flags_big (flag2 | flag3);' not described in enum 'flags'

Signed-off-by: Conchúr Navid <conchur@web.de>
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 125b906..8313b49 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1844,7 +1844,7 @@ sub dump_enum($$) {
     my $file = shift;
 
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
-    $x =~ s/^#\s*define\s+.*$//; # strip #define macros inside enums
+    $x =~ s@#\s*define\s+[^;]*;@@gos; # strip #define macros inside enums
 
     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
 	$declaration_name = $1;
-- 
2.6.2

[PATCH 2/3] kernel-doc: Strip #ifdef/#endif in enums

[conchur]

From: Conchúr Navid <conchur@web.de>

Some enumerations in the kernel headers use #ifdef to reduce their size
based on the the configuration. These lines have to be stripped to avoid
parsing problems.

For example a simple input like

    /**
     * enum flags - test flags
     * @flag1: first flag
     * @flag2: second flag
     */
    enum flags {
    	flag1 = BIT(0),
    #ifdef SECOND_FLAG
    	flag2 = BIT(1),
    #endif
    };

resulted in parsing warnings like

    warning: Enum value '#ifdef SECOND_FLAG;flag2 = BIT(1)' not described in enum 'flags'
    warning: Enum value '#endif;' not described in enum 'flags'

Signed-off-by: Conchúr Navid <conchur@web.de>
---
 scripts/kernel-doc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 8313b49..f5c2971 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1844,7 +1844,8 @@ sub dump_enum($$) {
     my $file = shift;
 
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
-    $x =~ s@#\s*define\s+[^;]*;@@gos; # strip #define macros inside enums
+    # strip #define macros inside enums
+    $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
 
     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
 	$declaration_name = $1;
-- 
2.6.2

[PATCH 3/3] kernel-doc: Strip #ifdef/#endif in enums

[conchur]

From: Conchúr Navid <conchur@web.de>

Some documented structures in the kernel use DECLARE_BITMAP to create
arrays of unsigned longs to store information using the bitmap functions.
These have to be replaced with a parsable version for kernel-doc.

For example a simple input like

    /**
     * struct something - some test
     * @members: active members
     */
    struct something {
    	DECLARE_BITMAP(members, MAX_MEMBERS);
    };

resulted in parsing warnings like

    warning: No description found for parameter 'MAX_MEMBERS)'
    warning: Excess struct/union/enum/typedef member 'members' description in 'something'

Signed-off-by: Conchúr Navid <conchur@web.de>
---
 scripts/kernel-doc | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f5c2971..9015b18 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1816,6 +1816,8 @@ sub dump_struct($$) {
 	$members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
 	$members =~ s/__aligned\s*\([^;]*\)//gos;
 	$members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
+	# replace DECLARE_BITMAP
+	$members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
 
 	create_parameterlist($members, ';', $file);
 	check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
-- 
2.6.2

[PATCHv2 3/3] kernel-doc: Fix parsing of DECLARE_BITMAP in struct

[conchur]

From: Conchúr Navid <conchur@web.de>

Some documented structures in the kernel use DECLARE_BITMAP to create
arrays of unsigned longs to store information using the bitmap functions.
These have to be replaced with a parsable version for kernel-doc.

For example a simple input like

    /**
     * struct something - some test
     * @members: active members
     */
    struct something {
    	DECLARE_BITMAP(members, MAX_MEMBERS);
    };

resulted in parsing warnings like

    warning: No description found for parameter 'MAX_MEMBERS)'
    warning: Excess struct/union/enum/typedef member 'members' description in 'something'

Signed-off-by: Conchúr Navid <conchur@web.de>
---
Update: Fix summary line

 scripts/kernel-doc | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f5c2971..9015b18 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1816,6 +1816,8 @@ sub dump_struct($$) {
 	$members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
 	$members =~ s/__aligned\s*\([^;]*\)//gos;
 	$members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
+	# replace DECLARE_BITMAP
+	$members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
 
 	create_parameterlist($members, ';', $file);
 	check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
-- 
2.6.2

Re: kernel-doc: Fix stripping of #define in enums

[Jonathan Corbet]

On Sun, 8 Nov 2015 10:45:23 +0100
conchur@web.de wrote:

> The regex to strip single line #define's in enumerations depends on the
> fact that the defines are still stored on separate lines. But the
> surrounding code already removed newlines and replaced them with
> semicolons.

So I've applied these to the docs tree for now...but they do not seem to
have any effect on the docs build.  What problem have you run into that
these changes solve?

Thanks,

jon

Aw: Re: kernel-doc: Fix stripping of #define in enums

[conchur]

> So I've applied these to the docs tree for now...but they do not seem to
> have any effect on the docs build. What problem have you run into that
> these changes solve?

Examples are given in the commit messages. And did you try to run kernel-doc against net/batman-adv/?