Re: [PATCH] scripts/kernel-doc: fix false pointer-to-function match for array members

[Randy Dunlap]

[ + Mauro]

On 9/23/26 10:39 AM, Jeff Johnson wrote:
> Currently 'scripts/kernel-doc -Wall -Werror -none' produces the following
> warnings for patch [1]:
> 
> Warning: include/linux/ieee80211-uhr.h:735 struct member 'valid_tid_bmap' not described in 'ieee80211_smd_ctx'
> Warning: include/linux/ieee80211-uhr.h:735 Excess struct member 'dl.valid_tid_bmap' description in 'ieee80211_smd_ctx' (did you mean one of: 'valid_tid_bmap', 'valid_ctx_bmap')
> Warning: include/linux/ieee80211-uhr.h:735 Excess struct member 'ul.valid_tid_bmap' description in 'ieee80211_smd_ctx' (did you mean one of: 'valid_tid_bmap', 'valid_ctx_bmap')
> 
> That patch contains the following (members not part of the issue have been
> removed):
> 
> /**
>  * struct ieee80211_smd_ctx - IEEE 802.11bn SMD Roaming Context (refer
>  *	IEEE P802.11bn/D2.0, Aug 2026, subclause 37.16.9)
>  *
>  * @valid_ctx_bmap: Bitmap indicating which context fields are valid;
>  *	bit positions defined by IEEE80211_SMD_CTX_VALID_* constants
>  * @dl: Down-link context data
>  * @dl.valid_tid_bmap: valid DL TIDs for which context is present
>  * @ul: Up-link context data
>  * @ul.valid_tid_bmap: valid UL TIDs for which context is present
>  */
> struct ieee80211_smd_ctx {
> 	DECLARE_BITMAP(valid_ctx_bmap, IEEE80211_SMD_CTX_NUM_VALID_CTX);
> 	struct {
> 		DECLARE_BITMAP(valid_tid_bmap, IEEE80211_SMD_CTX_NUM_TIDS);
> 	} dl;
> 	struct {
> 		DECLARE_BITMAP(valid_tid_bmap, IEEE80211_SMD_CTX_NUM_TIDS);
> 	} ul;
> };
> 
> rewrite_struct_members() processes each member of an embedded named
> struct/union. Before testing for a pointer-to-function declaration, it
> does not strip array notation from the member string. When DECLARE_BITMAP
> is expanded by the struct xforms to:
> 
>   unsigned long name[BITS_TO_LONGS(N)]
> 
> the subscript contains parentheses. The pointer-to-function regex
> '^([^\(]+\(\*?\s*)([\w.]*)(\s*\).*)' then greedily matches the leading
> portion up to the '(' inside the subscript, producing a garbled member
> name and losing the correct 'substruct.name' form.
> 
> Fix this by stripping array notation unconditionally before the
> pointer-to-function test, rather than only inside the else branch.
> This is safe because the array dimensions are not needed for either
> the pointer-to-function rewrite or the subsequent name extraction.
> 
> [1] https://lore.kernel.org/all/20260908-smd-v1-10-65ad4ab30fbd@xxxxxxxxxxxxxxxx/
> 
> Assisted-by: LLM
> Signed-off-by: Jeff Johnson <jeff.johnson@xxxxxxxxxxxxxxxx>
> ---
>  tools/lib/python/kdoc/kdoc_parser.py | 12 ++++++++++--
>  1 file changed, 10 insertions(+), 2 deletions(-)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
> index d9ad1ddc87dd..f097a13e47e2 100644
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -738,6 +738,15 @@ class KernelDoc:
>                      for arg in content.split(';'):
>                          arg = arg.strip()
>                          #
> +                        # Remove array portions. Array members whose
> +                        # dimensions are expressed as macro calls
> +                        # (e.g. DECLARE_BITMAP expansions) contain
> +                        # parentheses inside [...] that would otherwise
> +                        # cause a false match as a pointer-to-function
> +                        # declaration.
> +                        #
> +                        arg = KernRe(r'\[.*\]').sub('', arg)
> +                        #
>                          # Look for (type)(*name)(args) - pointer to function
>                          #
>                          r = KernRe(r'^([^\(]+\(\*?\s*)([\w.]*)(\s*\).*)')
> @@ -754,10 +763,9 @@ class KernelDoc:
>                          #
>                          else:
>                              #
> -                            # Remove bitmap and array portions and spaces around commas
> +                            # Remove bitfield portions and spaces around commas
>                              #
>                              arg = KernRe(r':\s*\d+\s*').sub('', arg)
> -                            arg = KernRe(r'\[.*\]').sub('', arg)
>                              arg = KernRe(r'\s*,\s*').sub(',', arg)
>                              #
>                              # Look for a normal decl - "type name[,name...]"
> 
> ---
> base-commit: 414f2b40f7b0244ea3ec1f7411d194a6d9c89c33
> change-id: 20260923-kerneldoc-embedded-bitmap-2e363ca11863
> 
> 

-- 
~Randy