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

[Jonathan Corbet]

Eric Biggers <ebiggers@xxxxxxxxxx> writes:

> 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/ kerneldoc 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])
>
> Signed-off-by: Eric Biggers <ebiggers@xxxxxxxxxx>
> ---
>  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..f982db7fddac2 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 = KernRe(r'\[at_least ').sub('[static ', arg)
> +

This could be a regular string replacement rather than a regex.  Not
something I'm willing to dig in my heels on, though... so if you want to
push this, either way:

Acked-by: Jonathan Corbet <corbet@xxxxxxx>

Thanks,

jon