Re: [PATCH] kernel-doc: add support for handling global variables

[Randy Dunlap <rdunlap@infradead.org>]

On 9/7/25 2:34 PM, Mauro Carvalho Chehab wrote:
> Em Sun,  7 Sep 2025 18:22:22 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:
> 
>> Specially on kAPI, sometimes it is desirable to be able to
>> describe global variables that are part of kAPI.
>>
>> Documenting vars with Sphinx is simple, as we don't need
>> to parse a data struct. All we need is the variable
>> declaration and use natice C domain ::c:var: to format it
>> for us.
>>
>> Add support for it.
>>
>> Link: https://lore.kernel.org/linux-doc/491c3022-cef8-4860-a945-c9c4a3b63c09@infradead.org/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1
>> Suggested-by: Randy Dunlap <rdunlap@infradead.org>
>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> 
> Btw, this is still at RFC level, as, for the final version we need:
> 
> - to document this new kernel-doc feature;

Yes, I thought of that one.

> - to suppress (or keep) the end ";";

I'll need to see it, but I expect I would prefer to suppress it.

> - do some cleanups/improvements at the regex to ensure that it is generic
>   enough. For instance, the way it was defineded, it doesn't handle yet
>   variables with assigned values like:
> 	extern int foo = 5;
> - if it has a default non-zero value, should it be documented or not,
>   and, if so, how;

I think I came up with some examples (test cases) like these without even
knowing that you had singled them out as possible issues.

> - to decide if we add "extern" to all outputs, to none of them or if we
>   just follow what is at the documented declaration (the current
>   implementation does the latter;

Follow what is documented for now (as you have it).

> - to decide weather use "global"/"var" or something else.

Just stick with "global". It's fine.

> Also, it would be interesting to have a real case where we want
> to document kAPI variables.
> 
> Randy,
> 
> if you have some real case examples, perhaps you could pick this patch
> and add on a patch series after taking the above into consideration.

I just searched for some real case examples and came up with around 6 from
various source files. I put them into one source file that I will include
in a Documentation/ .rst file for testing and let you know how that goes.

Sorry for the delay. I've had some other things going on.

Thanks for working on the feature.

-- 
~Randy