[PATCH] doc-rst: kernel-doc: fix handling of address_space tags

[PATCH] doc-rst: kernel-doc: fix handling of address_space tags

[Mauro Carvalho Chehab]

The RST cpp:function handler is very pedantic: it doesn't allow any
macros like __user on it:

	Documentation/media/kapi/dtv-core.rst:28: WARNING: Error when parsing function declaration.
	If the function has no return type:
	  Error in declarator or parameters and qualifiers
	  Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8]
	    ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
	    --------^
	If the function has a return type:
	  Error in declarator or parameters and qualifiers
	  If pointer to member declarator:
	    Invalid definition: Expected '::' in pointer to member (function). [error at 37]
	      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
	      -------------------------------------^
	  If declarator-id:
	    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102]
	      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
	      ------------------------------------------------------------------------------------------------------^

So, we have to remove it from the function prototype.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 scripts/kernel-doc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 41eade332307..4394746cc1aa 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1848,6 +1848,10 @@ sub output_function_rst(%) {
 	}
 	$count++;
 	$type = $args{'parametertypes'}{$parameter};
+
+	# RST doesn't like address_space tags at function prototypes
+	$type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//;
+
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
 	    print $1 . $parameter . ") (" . $2;
-- 
2.7.4

Re: [PATCH] doc-rst: kernel-doc: fix handling of address_space tags

[Jonathan Corbet]

On Fri, 22 Jul 2016 11:46:36 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> The RST cpp:function handler is very pedantic: it doesn't allow any
> macros like __user on it:
> [...]
> So, we have to remove it from the function prototype.

Sigh, this is the kind of thing where somehow there's always more moles
to whack.  I feel like there must be a better fix, but I don't know what
it is, so I've applied this, thanks.

I'm trying to get my act together so that the pull request can go in
right away once the merge window opens.  If there's anything else you
think really needs to be there, please do let me know.

jon

Re: [PATCH] doc-rst: kernel-doc: fix handling of address_space tags

[Mauro Carvalho Chehab]

Em Fri, 22 Jul 2016 15:37:16 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Fri, 22 Jul 2016 11:46:36 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > The RST cpp:function handler is very pedantic: it doesn't allow any
> > macros like __user on it:
> > [...]
> > So, we have to remove it from the function prototype.  
> 
> Sigh, this is the kind of thing where somehow there's always more moles
> to whack. 

Agreed.

> I feel like there must be a better fix, 

Well, we might create a "kernel-c" domain, I guess. I suspect we'll 
need something like that anyway, in order to handle things like
per-subsystem declarations of the syscalls (specially ioctl), but
I've no idea how difficult would be to do so.

For now, I guess that's the easiest fix.

> but I don't know what
> it is, so I've applied this, thanks.

Thank you!

> I'm trying to get my act together so that the pull request can go in
> right away once the merge window opens.  If there's anything else you
> think really needs to be there, please do let me know.

I suspect that that's it. There are a few trivial conflicts between
my tree and Daniel's one, as we both are adding new books at
Documentation/index.rst, but this is something that Stephen already
handled, and should be easy for Linus to handle as well.

Yet, if you prefer, you could pull from my docs-next branch, but
there are also lots of subsystem's patch on that, merged from
my master (stable) branch. So, if you pull from it and send to
Linus before me, you'll also be sending patches from the media
subsystem. Not really an issue, as, if Linus pull from my tree
later, he'll get only the few remains that aren't merged at my
docs-next branch.

Thanks,
Mauro

Re: [PATCH] doc-rst: kernel-doc: fix handling of address_space tags

[Markus Heiser]

Am 22.07.2016 um 16:46 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:

> The RST cpp:function handler is very pedantic: it doesn't allow any
> macros like __user on it:
> 
> 	Documentation/media/kapi/dtv-core.rst:28: WARNING: Error when parsing function declaration.
> 	If the function has no return type:
> 	  Error in declarator or parameters and qualifiers
> 	  Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8]
> 	    ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
> 	    --------^
> 	If the function has a return type:
> 	  Error in declarator or parameters and qualifiers
> 	  If pointer to member declarator:
> 	    Invalid definition: Expected '::' in pointer to member (function). [error at 37]
> 	      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
> 	      -------------------------------------^
> 	  If declarator-id:
> 	    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102]
> 	      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
> 	      ------------------------------------------------------------------------------------------------------^
> 

May I'am wrong, but as far as I know, we get this error only 
if we are using the CPP-domain. Since the kernel-doc parser
uses the C-domain, we should not have those error messages
(tested here with sphinx 1.4).

That said, I don't see the need to change the kernel-doc parser
eleminating the address_space tags.

Or did I missed some point?

-- Markus --

> So, we have to remove it from the function prototype.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
> scripts/kernel-doc | 4 ++++
> 1 file changed, 4 insertions(+)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 41eade332307..4394746cc1aa 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1848,6 +1848,10 @@ sub output_function_rst(%) {
> 	}
> 	$count++;
> 	$type = $args{'parametertypes'}{$parameter};
> +
> +	# RST doesn't like address_space tags at function prototypes
> +	$type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//;
> +
> 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
> 	    # pointer-to-function
> 	    print $1 . $parameter . ") (" . $2;
> -- 
> 2.7.4
> 
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html