Re: [PATCH 2/3] docs: split up the driver book

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

Em Wed, 24 Aug 2016 16:46:22 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Tue, 23 Aug 2016 11:30:16 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > On the output text, you'll see two places with "@:c:func:threadfn()".
> > 
> > The problem here is that threadfn() is a function argument. While this
> > used to work with DocBooks, now with Sphinx this is not handled well.
> > 
> > I got some other similar cases on media. There, I opted to just remove
> > the () on some places, or to replace it by \(\) to avoid kernel-doc
> > to do the wrong thing.   
> 
> I have a different idea: why not just add another regexp to the
> kernel-doc house of cards? :) 

Yeah, we can do that, but still we need to check if the references
are being properly solved (e. g. if the parser is doing the right
thing).

Ideally, the regex should also check for the next symbols, as
things like: @foo->bar should be translated to:
	:c:type:`foo`\ ->bar

As Sphinx doesn't handle well non-space chars[1] before :c: or after the
grave accent ("`").

[1] Actually, it seems to work fine with a few symbols, like commas
and dots.

> The following seems to make these issues
> go away pretty nicely, and didn't cause any change at all to the
> media/gpu output...
> 
> Stacking up ordering-dependent regexps is not a path to long-term joy; at
> some point, we will likely want a smarter parser for kerneldoc comments.
> But this seems to improve things for the moment.

Good!

> 
> jon
> 
> From 5dccd4fb9f3c0b6468f38efab8c1d6232d3e701b Mon Sep 17 00:00:00 2001
> From: Jonathan Corbet <corbet@lwn.net>
> Date: Wed, 24 Aug 2016 16:31:15 -0600
> Subject: [PATCH] docs: Special-case function-pointer parameters in kernel-doc
> 
> Add yet another regex to kernel-doc to trap @param() references separately
> and not produce corrupt RST markup.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  scripts/kernel-doc | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 4f2e9049e8fa..c681e8f0ecc2 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -212,6 +212,7 @@ my $anon_struct_union = 0;
>  my $type_constant = '\%([-_\w]+)';
>  my $type_func = '(\w+)\(\)';
>  my $type_param = '\@(\w+)';
> +my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
>  my $type_struct = '\&((struct\s*)*[_\w]+)';
>  my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
>  my $type_env = '(\$\w+)';
> @@ -292,6 +293,7 @@ my @highlights_rst = (
>                         # Note: need to escape () to avoid func matching later
>                         [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"],
>                         [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"],
> +		       [$type_fp_param, "**\$1\\\\(\\\\)**"],

Hmm... shoudn't it be a reference to the struct (or to the struct member),
instead of bold?

>                         [$type_func, "\\:c\\:func\\:`\$1()`"],
>                         [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
>                         [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],



Thanks,
Mauro