Hi Mauro, Thanks for the patch. On 10/30/20 7:00 AM, Mauro Carvalho Chehab wrote: > Em Fri, 30 Oct 2020 12:53:13 +0000 > Matthew Wilcox <willy@xxxxxxxxxxxxx> escreveu: > >> On Fri, Oct 30, 2020 at 01:28:59PM +0100, Markus Heiser wrote: >>> Am 30.10.20 um 12:31 schrieb Matthew Wilcox: >>>> On Fri, Oct 30, 2020 at 08:37:48AM +0100, Mauro Carvalho Chehab wrote: >>>>> Just changing the kernel-doc markup at kernel/futex.c: >>>>> >>>>> /** >>>>> * futex_setup_timer - set up the sleeping hrtimer. >>>>> * @time: ptr to the given timeout value >>>>> * @timeout: the hrtimer_sleeper structure to be set up >>>>> * @flags: futex flags >>>>> * @range_ns: optional range in ns >>>>> * >>>>> * Return: Initialized hrtimer_sleeper structure or NULL if no timeout >>>>> * value given >>>>> */ >>>>> >>>>> To: >>>>> >>>>> ... >>>>> * Return: >>>>> * >>>>> * Initialized hrtimer_sleeper structure or NULL if no timeout >>>>> * value given >>>>> */ >>>>> >>>>> Should fix it. >>>> >>>> Or just remove the indent. >>>> >>>> * Return: Initialized hrtimer_sleeper structure or NULL if no timeout >>>> * value given. >>> >>> To add my 2 cent: >>> >>> The return value should be described in a dedicated section >>> named "Return:", like shown im Mauro's example (compare [1]). >>> >>> For on-liners I think it is OK to use the short form (compare [2]). >>> >>> [1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values >>> [2] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation > > Yeah, I would use myself something like: > > Return: foo > > only for single-line returns, using: > > Return: > > foo > bar > > for multi-line ones. > > - > > Anyway, I tried the enclosed patch. With that, it should now recognize > kernel-doc markups with: > > * Return: Initialized hrtimer_sleeper structure or NULL if no timeout > * value given > > And: > > * Returns: 0 on success, -ENOSPC if no suitable hole is found, -EINTR if > * asked to wait for eviction and interrupted. > */ > (this example came from drivers/gpu/drm/i915/i915_gem_gtt.c) > > I only did a fast check here, in order to verify if it won't be > producing additional warnings. I didn't check the html output. > Just the resulting ReST from kernel-doc and the "make htmldocs" warnings. > > PS.: This handles only "Note(s)" and "Return(s)" sections. > Description and @var: are already handled using a different > logic elsewhere. > > This could likely be generalized, but more work (and tests) > are required. > > Thanks, > Mauro I can confirm that the bolding in struct hrtimer_sleeper * futex_setup_timer() is fixed after applying this patch. OTOH, the bolding for int seq_open() remains as it was previously. The only way that I could eliminate it was a small source file patch: --- fs/seq_file.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) --- linux-next-20201030.orig/fs/seq_file.c +++ linux-next-20201030/fs/seq_file.c @@ -47,7 +47,9 @@ static void *seq_buf_alloc(unsigned long * ERR_PTR(error). In the end of sequence they return %NULL. ->show() * returns 0 in case of success and negative number in case of error. * Returning SEQ_SKIP means "discard this element and move on". - * Note: seq_open() will allocate a struct seq_file and store its + * + * Note: + * seq_open() will allocate a struct seq_file and store its * pointer in @file->private_data. This pointer should not be modified. */ int seq_open(struct file *file, const struct seq_operations *op) > [PATCH] scripts: kernel-doc: better handle spaces after section markups > > Better handle things like: > > * Return: foo > * description > > Suggested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index f699cf05d409..a91a2420cccf 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -389,7 +389,7 @@ my $doc_com_body = '\s*\* ?'; > my $doc_decl = $doc_com . '(\w+)'; > # @params and a strictly limited set of supported section names > my $doc_sect = $doc_com . > - '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; > + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)(\s*:)(.*)'; > my $doc_content = $doc_com_body . '(.*)'; > my $doc_block = $doc_com . 'DOC:\s*(.*)?'; > my $doc_inline_start = '^\s*/\*\*\s*$'; > @@ -865,8 +865,21 @@ sub output_highlight_rst { > my $in_literal = 0; > my $litprefix; > my $block = ""; > + my $spaces = ""; > + my $first = 1; > > foreach $line (split "\n",$input) { > + if ($first) { > + $spaces = $1 if ($line =~ (m/^(\s+)/)); > + $first = 0; > + } > + > + if ($spaces ne "") { > + if (!($line =~ s/^$spaces//)) { > + $spaces = ""; > + } > + } > + > # > # If we're in a literal block, see if we should drop out > # of it. Otherwise pass the line straight through unmunged. > @@ -2135,8 +2148,9 @@ sub process_body($$) { > } > > if (/$doc_sect/i) { # case insensitive for supported section names > + my $spaces = "$1$2"; > $newsection = $1; > - $newcontents = $2; > + $newcontents = $3; > > # map the supported section names to the canonical names > if ($newsection =~ m/^description$/i) { > @@ -2161,11 +2175,20 @@ sub process_body($$) { > > $in_doc_sect = 1; > $state = STATE_BODY; > - $contents = $newcontents; > $new_start_line = $.; > - while (substr($contents, 0, 1) eq " ") { > - $contents = substr($contents, 1); > + > + if ($newsection =~ m/(return|note)/i) { > + $spaces =~ s/\S/ /g; > + $newcontents = $spaces . $newcontents; > + $newcontents =~ s/^\s+$//; > + $contents = $newcontents; > + } else { > + $contents = $newcontents; > + while (substr($newcontents, 0, 1) eq " ") { > + $newcontents = substr($newcontents, 1); > + } > } > + > if ($contents ne "") { > $contents .= "\n"; > } > > -- ~Randy
