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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Mon, 8 Sep 2025 23:22:13 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:

> 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.

Ok. Yeah, that's probably the better.

> > - 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.

Sounds good. Yeah, having some real-case scenarios will help discovering
what else we need for the regex and for the output.

> > - 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).

Ok.

> > - to decide weather use "global"/"var" or something else.  
> 
> Just stick with "global". It's fine.

Ok.

> > 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.

No problem. Take your time.

> Thanks for working on the feature.

Anytime.

Thanks,
Mauro