Re: [PATCH v2 1/2] docs: kdoc: Expand 'at_least' when creating parameter list

[Randy Dunlap]

On 4/18/26 12:21 PM, Eric Biggers wrote:
> sphinx doesn't know that the kernel headers do:
> 
>     #define at_least static
> 
> Do this replacement before declarations are passed to it.
> 
> This prevents errors like the following from appearing once the
> lib/crypto/ kernel-doc is wired up to the sphinx build:
> 
>    linux/Documentation/crypto/libcrypto:128: ./include/crypto/sha2.h:773: WARNING: Error in declarator or parameters
> Error in declarator or parameters
> Invalid C declaration: Expected ']' in end of array operator. [error at 59]
>   void sha512_final (struct sha512_ctx *ctx, u8 out[at_least SHA512_DIGEST_SIZE])
> 
> Acked-by: Jonathan Corbet <corbet@xxxxxxx>
> Reviewed-by: Ard Biesheuvel <ardb@xxxxxxxxxx>
> Signed-off-by: Eric Biggers <ebiggers@xxxxxxxxxx>

Acked-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>

> ---
>  tools/lib/python/kdoc/kdoc_parser.py | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
> index 74af7ae47aa47..c3f966da533e0 100644
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -437,10 +437,15 @@ class KernelDoc:
>  
>          for arg in args.split(splitter):
>              # Ignore argument attributes
>              arg = KernRe(r'\sPOS0?\s').sub(' ', arg)
>  
> +            # Replace '[at_least ' with '[static '.  This allows sphinx to parse
> +            # array parameter declarations like 'char A[at_least 4]', where
> +            # 'at_least' is #defined to 'static' by the kernel headers.
> +            arg = arg.replace('[at_least ', '[static ')
> +
>              # Strip leading/trailing spaces
>              arg = arg.strip()
>              arg = KernRe(r'\s+').sub(' ', arg, count=1)
>  
>              if arg.startswith('#'):

-- 
~Randy