Em Mon, 8 Sep 2025 23:22:13 -0700 Randy Dunlap <rdunlap@xxxxxxxxxxxxx> 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@xxxxxxxxxx> 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@xxxxxxxxxxxxx/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1 > >> Suggested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> > >> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> > > > > 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
