| Message ID | 46c52676-c402-4b39-b634-a401f7a7a571@infradead.org (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | [partial,fix] Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags | expand |
On 10/10/24 4:43 PM, Randy Dunlap wrote: > > > On 10/9/24 10:06 PM, Randy Dunlap wrote: >> >> >> On 10/9/24 3:02 PM, Randy Dunlap wrote: >>> >>> >>> On 10/9/24 9:49 AM, Jonathan Corbet wrote: >>>> Vlastimil Babka <vbabka@suse.cz> writes: >>>> >>>>> Thanks for the hints. I hope if we can agree that documenting the macros was >>>>> intended to be supported, doesn't break the build (there are users already) >>>>> and has only those minor rendering issues, it can be used? >>>> >>>> I'd totally forgotten that this was supposed to work. >>>> >>>> Yes it can be used... $WE just need to find a way to make it work >>>> properly. >>> >>> The code probably isn't expecting a macro on the right side. I'll take a look, >>> but no promises. >>> >> That would have been too simple. >> I haven't found the problem yet. Ran out of time. Will continue on it tommorrow/Thursday. > > The main problem is that output_function_rst() does not support object-like macros while > output_function_man() does. There is still a bunch of sphinx_version handling that I know > nothing about, so the present output (after my trivial patch) leaves more to be done. > > Well, the *main* problem is that the output is not consistent. Sometimes my tests don't fail > as they did at first. > > > This patch drops the trailing "()" for object-like macros in output_function_rst() > but there is still more to be done. > > --------------------- > From: Randy Dunlap <rdunlap@infradead.org> > Subject: [PATCH] kernel-doc: allow object-like macros in ReST output > > output_function_rst() does not handle object-like macros. It presents > a trailing "()" while output_function_man() handles these macros > correctly. > > Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") > Signed-off-by: Randy Dunlap <rdunlap@infradead.org> > Cc: Horia Geanta <horia.geanta@freescale.com> > Cc: Jonathan Corbet <corbet@lwn.net> > Cc: linux-doc@vger.kernel.org > Cc: Vlastimil Babka <vbabka@suse.cz> > --- > scripts/kernel-doc | 8 ++++++-- > 1 file changed, 6 insertions(+), 2 deletions(-) > > --- linux-next-20241009.orig/scripts/kernel-doc > +++ linux-next-20241009/scripts/kernel-doc > @@ -822,10 +822,12 @@ sub output_function_rst(%) { > my $oldprefix = $lineprefix; > > my $signature = ""; > + my $noret = $signature eq ""; ^^^ That line is in the wrong location. Still working on it.... > + > if ($args{'functiontype'} ne "") { > $signature = $args{'functiontype'} . " " . $args{'function'} . " ("; > } else { > - $signature = $args{'function'} . " ("; > + $signature = $args{'function'} . " "; > } > > my $count = 0; > @@ -844,7 +846,9 @@ sub output_function_rst(%) { > } > } > > - $signature .= ")"; > + if (!$noret) { > + $signature .= ")"; > + } > > if ($sphinx_major < 3) { > if ($args{'typedef'}) { > >
On 10/10/24 4:54 PM, Randy Dunlap wrote: > > > On 10/10/24 4:43 PM, Randy Dunlap wrote: >> >> >> On 10/9/24 10:06 PM, Randy Dunlap wrote: >>> >>> >>> On 10/9/24 3:02 PM, Randy Dunlap wrote: >>>> >>>> >>>> On 10/9/24 9:49 AM, Jonathan Corbet wrote: >>>>> Vlastimil Babka <vbabka@suse.cz> writes: >>>>> >> >> The main problem is that output_function_rst() does not support object-like macros while >> output_function_man() does. There is still a bunch of sphinx_version handling that I know >> nothing about, so the present output (after my trivial patch) leaves more to be done. >> >> Well, the *main* problem is that the output is not consistent. Sometimes my tests don't fail >> as they did at first. >> >> >> This patch drops the trailing "()" for object-like macros in output_function_rst() >> but there is still more to be done. >> >> --------------------- This one mostly works for me although I don't care for the second line here. I guess it has something to do with cross-referencing(?), but IDK. """ SLAB_TYPESAFE_BY_RCU ``SLAB_TYPESAFE_BY_RCU `` WARNING READ THIS! Description """ --- From: Randy Dunlap <rdunlap@infradead.org> Subject: [PATCH] kernel-doc: allow object-like macros in ReST output output_function_rst() does not handle object-like macros. It presents a trailing "()" while output_function_man() handles these macros correctly. Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Horia Geanta <horia.geanta@freescale.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Cc: Vlastimil Babka <vbabka@suse.cz> --- scripts/kernel-doc | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) --- linux-next-20241009.orig/scripts/kernel-doc +++ linux-next-20241009/scripts/kernel-doc @@ -822,10 +822,13 @@ sub output_function_rst(%) { my $oldprefix = $lineprefix; my $signature = ""; + my $noret = 0; + if ($args{'functiontype'} ne "") { $signature = $args{'functiontype'} . " " . $args{'function'} . " ("; } else { - $signature = $args{'function'} . " ("; + $signature = $args{'function'} . " "; + $noret = 1; } my $count = 0; @@ -844,7 +847,9 @@ sub output_function_rst(%) { } } - $signature .= ")"; + if (!$noret) { + $signature .= ")"; + } if ($sphinx_major < 3) { if ($args{'typedef'}) { @@ -890,7 +895,9 @@ sub output_function_rst(%) { # print ".. container:: kernelindent\n\n"; $lineprefix = " "; - print $lineprefix . "**Parameters**\n\n"; + if (!$noret) { + print $lineprefix . "**Parameters**\n\n"; + } foreach $parameter (@{$args{'parameterlist'}}) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//;
On 10/10/24 8:07 PM, Randy Dunlap wrote: > > > On 10/10/24 4:54 PM, Randy Dunlap wrote: >> >> >> On 10/10/24 4:43 PM, Randy Dunlap wrote: >>> >>> >>> On 10/9/24 10:06 PM, Randy Dunlap wrote: >>>> >>>> >>>> On 10/9/24 3:02 PM, Randy Dunlap wrote: >>>>> >>>>> >>>>> On 10/9/24 9:49 AM, Jonathan Corbet wrote: >>>>>> Vlastimil Babka <vbabka@suse.cz> writes: >>>>>> >>> >>> The main problem is that output_function_rst() does not support object-like macros while >>> output_function_man() does. There is still a bunch of sphinx_version handling that I know >>> nothing about, so the present output (after my trivial patch) leaves more to be done. >>> >>> Well, the *main* problem is that the output is not consistent. Sometimes my tests don't fail >>> as they did at first. >>> >>> >>> This patch drops the trailing "()" for object-like macros in output_function_rst() >>> but there is still more to be done. >>> >>> --------------------- > > This one mostly works for me although I don't care for the second line > here. I guess it has something to do with cross-referencing(?), but IDK. > That seems to be normal but this patch now causes regressions for macros that do have parameters. Back to searching... > > """ > SLAB_TYPESAFE_BY_RCU > ``SLAB_TYPESAFE_BY_RCU `` > > WARNING READ THIS! > > Description > """ > > --- > From: Randy Dunlap <rdunlap@infradead.org> > Subject: [PATCH] kernel-doc: allow object-like macros in ReST output > > output_function_rst() does not handle object-like macros. It presents > a trailing "()" while output_function_man() handles these macros > correctly. > > Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") > Signed-off-by: Randy Dunlap <rdunlap@infradead.org> > Cc: Horia Geanta <horia.geanta@freescale.com> > Cc: Jonathan Corbet <corbet@lwn.net> > Cc: linux-doc@vger.kernel.org > Cc: Vlastimil Babka <vbabka@suse.cz> > --- > scripts/kernel-doc | 13 ++++++++++--- > 1 file changed, 10 insertions(+), 3 deletions(-) > > --- linux-next-20241009.orig/scripts/kernel-doc > +++ linux-next-20241009/scripts/kernel-doc > @@ -822,10 +822,13 @@ sub output_function_rst(%) { > my $oldprefix = $lineprefix; > > my $signature = ""; > + my $noret = 0; > + > if ($args{'functiontype'} ne "") { > $signature = $args{'functiontype'} . " " . $args{'function'} . " ("; > } else { > - $signature = $args{'function'} . " ("; > + $signature = $args{'function'} . " "; > + $noret = 1; > } > > my $count = 0; > @@ -844,7 +847,9 @@ sub output_function_rst(%) { > } > } > > - $signature .= ")"; > + if (!$noret) { > + $signature .= ")"; > + } > > if ($sphinx_major < 3) { > if ($args{'typedef'}) { > @@ -890,7 +895,9 @@ sub output_function_rst(%) { > # > print ".. container:: kernelindent\n\n"; > $lineprefix = " "; > - print $lineprefix . "**Parameters**\n\n"; > + if (!$noret) { > + print $lineprefix . "**Parameters**\n\n"; > + } > foreach $parameter (@{$args{'parameterlist'}}) { > my $parameter_name = $parameter; > $parameter_name =~ s/\[.*//; > >
--- linux-next-20241009.orig/scripts/kernel-doc +++ linux-next-20241009/scripts/kernel-doc @@ -822,10 +822,12 @@ sub output_function_rst(%) { my $oldprefix = $lineprefix; my $signature = ""; + my $noret = $signature eq ""; + if ($args{'functiontype'} ne "") { $signature = $args{'functiontype'} . " " . $args{'function'} . " ("; } else { - $signature = $args{'function'} . " ("; + $signature = $args{'function'} . " "; } my $count = 0; @@ -844,7 +846,9 @@ sub output_function_rst(%) { } } - $signature .= ")"; + if (!$noret) { + $signature .= ")"; + } if ($sphinx_major < 3) { if ($args{'typedef'}) {