Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1469770

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

Show all headers | View raw

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

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\\\\(\\\\)**"],
                        [$type_func, "\\:c\\:func\\:`\$1()`"],
                        [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
                        [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
-- 
2.7.4

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH 0/3] RFC: The beginning of a proper driver-api book Jonathan Corbet <corbet@lwn.net> - 2016-08-22 23:00 +0200
  [PATCH 3/3] docs: Pull HSI documentation together Jonathan Corbet <corbet@lwn.net> - 2016-08-22 23:00 +0200
    Re: [PATCH 3/3] docs: Pull HSI documentation together Sebastian Reichel <sre@kernel.org> - 2016-08-23 02:30 +0200
      Re: [PATCH 3/3] docs: Pull HSI documentation together Jonathan Corbet <corbet@lwn.net> - 2016-09-06 17:20 +0200
  [PATCH 1/3] Docs: sphinxify device-drivers.tmpl Jonathan Corbet <corbet@lwn.net> - 2016-08-22 23:00 +0200
  [PATCH 2/3] docs: split up the driver book Jonathan Corbet <corbet@lwn.net> - 2016-08-22 23:00 +0200
    Re: [PATCH 2/3] docs: split up the driver book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-08-23 16:40 +0200
      Re: [PATCH 2/3] docs: split up the driver book Jonathan Corbet <corbet@lwn.net> - 2016-08-25 00:50 +0200
        Re: [PATCH 2/3] docs: split up the driver book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-08-25 07:40 +0200
      Re: [PATCH 2/3] docs: split up the driver book Jonathan Corbet <corbet@lwn.net> - 2016-08-25 22:10 +0200
  Re: [PATCH 0/3] RFC: The beginning of a proper driver-api book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-08-23 16:50 +0200
    Re: [PATCH 0/3] RFC: The beginning of a proper driver-api book Markus Heiser <markus.heiser@darmarit.de> - 2016-08-26 11:40 +0200
      Re: [PATCH 0/3] RFC: The beginning of a proper driver-api book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-08-26 12:10 +0200
        Re: [PATCH 0/3] RFC: The beginning of a proper driver-api book Jani Nikula <jani.nikula@intel.com> - 2016-08-26 12:20 +0200

csiph-web