[PATCH v3] docs-rst: ignore arguments on macro definitions

[PATCH v3] docs-rst: ignore arguments on macro definitions

[Mauro Carvalho Chehab]

A macro definition is mapped via .. c:function:: at the
ReST markup when using the following kernel-doc tag:

	/**
	 * DMX_FE_ENTRY - Casts elements in the list of registered
	 *               front-ends from the generic type struct list_head
	 *               to the type * struct dmx_frontend
	 *
	 * @list: list of struct dmx_frontend
	 */
	 #define DMX_FE_ENTRY(list) \
	        list_entry(list, struct dmx_frontend, connectivity_list)

However, unlike a function description, the arguments of a macro
doesn't contain the data type.

This causes warnings when enabling Sphinx on nitkpick mode,
like this one:
	./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not found: list

That happens because kernel-doc output for the above is:

	.. c:function:: DMX_FE_ENTRY ( list)

	   Casts elements in the list of registered front-ends from the generic type struct list_head to the type * struct dmx_frontend

	**Parameters**

	``list``
	  list of struct dmx_frontend

As the type is blank, Sphinx would think that ``list`` is a type,
and will try to add a cross reference for it, using their internal
representation for c:type:`list`.

However, ``list`` is not a type. So, that would cause either the
above warning, or if a ``list`` type exists, it would create
a reference to the wrong place at the doc.

To avoid that, let's ommit macro arguments from c:function::
declaration. As each argument will appear below the Parameters,
the type of the argument can be described there, if needed.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---

v3: version 2 patch caused a regression when handling function arguments,
because the counter were not incremented on all cases. Fix it.

 scripts/kernel-doc | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index d225e178aa1b..bac0af4fc659 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1846,14 +1846,15 @@ sub output_function_rst(%) {
 	if ($count ne 0) {
 	    print ", ";
 	}
-	$count++;
 	$type = $args{'parametertypes'}{$parameter};
 
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
 	    print $1 . $parameter . ") (" . $2;
-	} else {
+	    $count++;
+	} elsif ($type ne "") {
 	    print $type . " " . $parameter;
+	    $count++;
 	}
     }
     print ")\n\n";
-- 
2.7.4

Re: [PATCH v3] docs-rst: ignore arguments on macro definitions

[Markus Heiser]

Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:

> A macro definition is mapped via .. c:function:: at the
> ReST markup when using the following kernel-doc tag:
> 
> 	/**
> 	 * DMX_FE_ENTRY - Casts elements in the list of registered
> 	 *               front-ends from the generic type struct list_head
> 	 *               to the type * struct dmx_frontend
> 	 *
> 	 * @list: list of struct dmx_frontend
> 	 */
> 	 #define DMX_FE_ENTRY(list) \
> 	        list_entry(list, struct dmx_frontend, connectivity_list)
> 
> However, unlike a function description, the arguments of a macro
> doesn't contain the data type.
> 
> This causes warnings when enabling Sphinx on nitkpick mode,
> like this one:
> 	./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not found: list

I think this is a drawback of sphinx's C-domain, using function
definition for macros also. From the function documentation

 """This is also used to describe function-like preprocessor
    macros. The names of the arguments should be given so
    they may be used in the description."""

I think about to fix the nitpick message for macros (aka function
directive) in the C-domain extension (we already have).

But for this, I need a rule to distinguish between macros
and functions ... is the uppercase of the macro name a good
rule to suppress the nitpick message? Any other suggestions?

-- Markus --

> 
> That happens because kernel-doc output for the above is:
> 
> 	.. c:function:: DMX_FE_ENTRY ( list)
> 
> 	   Casts elements in the list of registered front-ends from the generic type struct list_head to the type * struct dmx_frontend
> 
> 	**Parameters**
> 
> 	``list``
> 	  list of struct dmx_frontend
> 
> As the type is blank, Sphinx would think that ``list`` is a type,
> and will try to add a cross reference for it, using their internal
> representation for c:type:`list`.
> 
> However, ``list`` is not a type. So, that would cause either the
> above warning, or if a ``list`` type exists, it would create
> a reference to the wrong place at the doc.
> 
> To avoid that, let's ommit macro arguments from c:function::
> declaration. As each argument will appear below the Parameters,
> the type of the argument can be described there, if needed.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
> 
> v3: version 2 patch caused a regression when handling function arguments,
> because the counter were not incremented on all cases. Fix it.
> 
> scripts/kernel-doc | 5 +++--
> 1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index d225e178aa1b..bac0af4fc659 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1846,14 +1846,15 @@ sub output_function_rst(%) {
> 	if ($count ne 0) {
> 	    print ", ";
> 	}
> -	$count++;
> 	$type = $args{'parametertypes'}{$parameter};
> 
> 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
> 	    # pointer-to-function
> 	    print $1 . $parameter . ") (" . $2;
> -	} else {
> +	    $count++;
> +	} elsif ($type ne "") {
> 	    print $type . " " . $parameter;
> +	    $count++;
> 	}
>    }
>    print ")\n\n";
> -- 
> 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

Re: [PATCH v3] docs-rst: ignore arguments on macro definitions

[Mauro Carvalho Chehab]

Em Mon, 29 Aug 2016 16:12:39 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 
> > A macro definition is mapped via .. c:function:: at the
> > ReST markup when using the following kernel-doc tag:
> > 
> > 	/**
> > 	 * DMX_FE_ENTRY - Casts elements in the list of registered
> > 	 *               front-ends from the generic type struct list_head
> > 	 *               to the type * struct dmx_frontend
> > 	 *
> > 	 * @list: list of struct dmx_frontend
> > 	 */
> > 	 #define DMX_FE_ENTRY(list) \
> > 	        list_entry(list, struct dmx_frontend, connectivity_list)
> > 
> > However, unlike a function description, the arguments of a macro
> > doesn't contain the data type.
> > 
> > This causes warnings when enabling Sphinx on nitkpick mode,
> > like this one:
> > 	./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not found: list  
> 
> I think this is a drawback of sphinx's C-domain, using function
> definition for macros also. From the function documentation
> 
>  """This is also used to describe function-like preprocessor
>     macros. The names of the arguments should be given so
>     they may be used in the description."""
> 
> I think about to fix the nitpick message for macros (aka function
> directive) in the C-domain extension (we already have).

Yeah, that could produce a better output, if it is doable.

> 
> But for this, I need a rule to distinguish between macros
> and functions ... is the uppercase of the macro name a good
> rule to suppress the nitpick message? 

No. There are lots of macros in lowercase. never did any stats about
that, but I guess that we actually have a way more such macros in
lowercase.

> Any other suggestions?

I guess the best thing is to check if the type is empty, just like
on this patch. Macros are always:
	foo(arg1, arg2, arg3, ...)

while functions always have some type (with could be as complex as
a function pointer). So, if all arguments match this rejex:
	\s*\S+\s*
Then, it is a macro. Otherwise, it is a function.

There's no way for the C domain to distinguish between a macro or
a function when the number of arguments is zero, but, on such case,
it doesn't really matter.

Thanks,
Mauro

Re: [PATCH v3] docs-rst: ignore arguments on macro definitions

[Jani Nikula]

On Mon, 29 Aug 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> Em Mon, 29 Aug 2016 16:12:39 +0200
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
>
>> Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>> 
>> > A macro definition is mapped via .. c:function:: at the
>> > ReST markup when using the following kernel-doc tag:
>> > 
>> > 	/**
>> > 	 * DMX_FE_ENTRY - Casts elements in the list of registered
>> > 	 *               front-ends from the generic type struct list_head
>> > 	 *               to the type * struct dmx_frontend
>> > 	 *
>> > 	 * @list: list of struct dmx_frontend
>> > 	 */
>> > 	 #define DMX_FE_ENTRY(list) \
>> > 	        list_entry(list, struct dmx_frontend, connectivity_list)
>> > 
>> > However, unlike a function description, the arguments of a macro
>> > doesn't contain the data type.
>> > 
>> > This causes warnings when enabling Sphinx on nitkpick mode,
>> > like this one:
>> > 	./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not found: list  
>> 
>> I think this is a drawback of sphinx's C-domain, using function
>> definition for macros also. From the function documentation
>> 
>>  """This is also used to describe function-like preprocessor
>>     macros. The names of the arguments should be given so
>>     they may be used in the description."""
>> 
>> I think about to fix the nitpick message for macros (aka function
>> directive) in the C-domain extension (we already have).
>
> Yeah, that could produce a better output, if it is doable.
>
>> 
>> But for this, I need a rule to distinguish between macros
>> and functions ... is the uppercase of the macro name a good
>> rule to suppress the nitpick message? 
>
> No. There are lots of macros in lowercase. never did any stats about
> that, but I guess that we actually have a way more such macros in
> lowercase.
>
>> Any other suggestions?
>
> I guess the best thing is to check if the type is empty, just like
> on this patch. Macros are always:
> 	foo(arg1, arg2, arg3, ...)
>
> while functions always have some type (with could be as complex as
> a function pointer). So, if all arguments match this rejex:
> 	\s*\S+\s*
> Then, it is a macro. Otherwise, it is a function.
>
> There's no way for the C domain to distinguish between a macro or
> a function when the number of arguments is zero, but, on such case,
> it doesn't really matter.

What does Sphinx say if you add "void" as the type? Or a fake
"macroparam" type?

If those hacks don't help, Mauro's suggestion seems sane.

BR,
Jani.



>
> Thanks,
> Mauro
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH v3] docs-rst: ignore arguments on macro definitions

[Markus Heiser]

Am 29.08.2016 um 17:36 schrieb Jani Nikula <jani.nikula@linux.intel.com>:

> On Mon, 29 Aug 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
>> Em Mon, 29 Aug 2016 16:12:39 +0200
>> Markus Heiser <markus.heiser@darmarit.de> escreveu:
>> 
>>> Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>>> 
>>>> A macro definition is mapped via .. c:function:: at the
>>>> ReST markup when using the following kernel-doc tag:
>>>> 
>>>> 	/**
>>>> 	 * DMX_FE_ENTRY - Casts elements in the list of registered
>>>> 	 *               front-ends from the generic type struct list_head
>>>> 	 *               to the type * struct dmx_frontend
>>>> 	 *
>>>> 	 * @list: list of struct dmx_frontend
>>>> 	 */
>>>> 	 #define DMX_FE_ENTRY(list) \
>>>> 	        list_entry(list, struct dmx_frontend, connectivity_list)
>>>> 
>>>> However, unlike a function description, the arguments of a macro
>>>> doesn't contain the data type.
>>>> 
>>>> This causes warnings when enabling Sphinx on nitkpick mode,
>>>> like this one:
>>>> 	./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not found: list  
>>> 
>>> I think this is a drawback of sphinx's C-domain, using function
>>> definition for macros also. From the function documentation
>>> 
>>> """This is also used to describe function-like preprocessor
>>>    macros. The names of the arguments should be given so
>>>    they may be used in the description."""
>>> 
>>> I think about to fix the nitpick message for macros (aka function
>>> directive) in the C-domain extension (we already have).
>> 
>> Yeah, that could produce a better output, if it is doable.
>> 
>>> 
>>> But for this, I need a rule to distinguish between macros
>>> and functions ... is the uppercase of the macro name a good
>>> rule to suppress the nitpick message? 
>> 
>> No. There are lots of macros in lowercase. never did any stats about
>> that, but I guess that we actually have a way more such macros in
>> lowercase.
>> 
>>> Any other suggestions?
>> 
>> I guess the best thing is to check if the type is empty, just like
>> on this patch. Macros are always:
>> 	foo(arg1, arg2, arg3, ...)

Yes, it is so clear, ... I'am a gawk ;-)

>> while functions always have some type (with could be as complex as
>> a function pointer). So, if all arguments match this rejex:
>> 	\s*\S+\s*
>> Then, it is a macro. Otherwise, it is a function.
>> 
>> There's no way for the C domain to distinguish between a macro or
>> a function when the number of arguments is zero, but, on such case,
>> it doesn't really matter.
> 
> What does Sphinx say if you add "void" as the type? Or a fake
> "macroparam" type?

Hi Jani, sorry for my late reply,

I haven't tested your suggestion, but since *void* is in the list
of stop-words:

    # These C types aren't described anywhere, so don't try to create
    # a cross-reference to them
    stopwords = set((
        'const', 'void', 'char', 'wchar_t', 'int', 'short',
        'long', 'float', 'double', 'unsigned', 'signed', 'FILE',
        'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t',
        'struct', '_Bool',
    ))

I think it will work in the matter you think. 

However I like to prefer to fix it in the C-domain, using
Mauro's suggestion on argument parsing. IMHO it is not
the best solution to add a void type to the reST signature
of a macro. This will result in a unusual output and does
not fix what is wrong in Sphinx's c-domain (there is also
a drawback in the index, where a function-type macro is
referred as function, not as macro).

I will give it a try, to eliminate these drawbacks in 
the C-domain and send a patch series, we can discuss further.

-- Markus --


> 
> If those hacks don't help, Mauro's suggestion seems sane.
> 
> BR,
> Jani.
> 
> 
> 
>> 
>> Thanks,
>> Mauro
>> --
>> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center

Re: [PATCH v3] docs-rst: ignore arguments on macro definitions

[Jani Nikula]

On Wed, 31 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> I haven't tested your suggestion, but since *void* is in the list
> of stop-words:
>
>     # These C types aren't described anywhere, so don't try to create
>     # a cross-reference to them
>     stopwords = set((
>         'const', 'void', 'char', 'wchar_t', 'int', 'short',
>         'long', 'float', 'double', 'unsigned', 'signed', 'FILE',
>         'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t',
>         'struct', '_Bool',
>     ))
>
> I think it will work in the matter you think. 
>
> However I like to prefer to fix it in the C-domain, using
> Mauro's suggestion on argument parsing. IMHO it is not
> the best solution to add a void type to the reST signature
> of a macro. This will result in a unusual output and does
> not fix what is wrong in Sphinx's c-domain (there is also
> a drawback in the index, where a function-type macro is
> referred as function, not as macro).

>From an API user's perspective, functions and function-like macros
should work interchangeably. Personally, I don't think there needs to be
a difference in the index. This seems to be the approach taken in
Sphinx, but it just doesn't work well for automatic documentation
generation because we can't deduce the parameter types from the macro
definition.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH v3] docs-rst: ignore arguments on macro definitions

[Markus Heiser]

Am 31.08.2016 um 11:02 schrieb Jani Nikula <jani.nikula@linux.intel.com>:

> On Wed, 31 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
>> I haven't tested your suggestion, but since *void* is in the list
>> of stop-words:
>> 
>>    # These C types aren't described anywhere, so don't try to create
>>    # a cross-reference to them
>>    stopwords = set((
>>        'const', 'void', 'char', 'wchar_t', 'int', 'short',
>>        'long', 'float', 'double', 'unsigned', 'signed', 'FILE',
>>        'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t',
>>        'struct', '_Bool',
>>    ))
>> 
>> I think it will work in the matter you think. 
>> 
>> However I like to prefer to fix it in the C-domain, using
>> Mauro's suggestion on argument parsing. IMHO it is not
>> the best solution to add a void type to the reST signature
>> of a macro. This will result in a unusual output and does
>> not fix what is wrong in Sphinx's c-domain (there is also
>> a drawback in the index, where a function-type macro is
>> referred as function, not as macro).
> 
> From an API user's perspective, functions and function-like macros
> should work interchangeably.

Ah, OK.

> Personally, I don't think there needs to be
> a difference in the index. This seems to be the approach taken in
> Sphinx, but it just doesn't work well for automatic documentation
> generation because we can't deduce the parameter types from the macro
> definition.

In the index, sphinx refers only object-like macros with an entry 
"FOO (C macro))". Function-like macros are referred as "BAR (C function)".

I thought it is more straight forward to refer all macros with a 
"BAR (C macro)" entry in the index. I will split this change in
a separate patch, so we can decide if we like to patch the index
that way.

But now, as we discuss this, I have another doubt to fix the index.
It might be confusing when writing references to those macros.

Since function-like macros internally are functions in the c-domain, 
they are referred with ":c:func:`BAR`". On the other side, object-like
macros are referred by role ":c:macro:`FOO`".

Taking this into account, it might be one reason more to follow
your conclusion that functions and function-like macros are 
interchangeable from the user's perspective.

-- Markus --

> 
> BR,
> Jani.
> 
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3] docs-rst: ignore arguments on macro definitions

[Mauro Carvalho Chehab]

Em Wed, 31 Aug 2016 12:09:39 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 31.08.2016 um 11:02 schrieb Jani Nikula <jani.nikula@linux.intel.com>:
> 
> > On Wed, 31 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:  
> >> I haven't tested your suggestion, but since *void* is in the list
> >> of stop-words:
> >> 
> >>    # These C types aren't described anywhere, so don't try to create
> >>    # a cross-reference to them
> >>    stopwords = set((
> >>        'const', 'void', 'char', 'wchar_t', 'int', 'short',
> >>        'long', 'float', 'double', 'unsigned', 'signed', 'FILE',
> >>        'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t',
> >>        'struct', '_Bool',
> >>    ))
> >> 
> >> I think it will work in the matter you think. 
> >> 
> >> However I like to prefer to fix it in the C-domain, using
> >> Mauro's suggestion on argument parsing. IMHO it is not
> >> the best solution to add a void type to the reST signature
> >> of a macro. This will result in a unusual output and does
> >> not fix what is wrong in Sphinx's c-domain (there is also
> >> a drawback in the index, where a function-type macro is
> >> referred as function, not as macro).  
> > 
> > From an API user's perspective, functions and function-like macros
> > should work interchangeably.  
> 
> Ah, OK.
> 
> > Personally, I don't think there needs to be
> > a difference in the index. This seems to be the approach taken in
> > Sphinx, but it just doesn't work well for automatic documentation
> > generation because we can't deduce the parameter types from the macro
> > definition.  
> 
> In the index, sphinx refers only object-like macros with an entry 
> "FOO (C macro))". Function-like macros are referred as "BAR (C function)".
> 
> I thought it is more straight forward to refer all macros with a 
> "BAR (C macro)" entry in the index. I will split this change in
> a separate patch, so we can decide if we like to patch the index
> that way.
>
> But now, as we discuss this, I have another doubt to fix the index.
> It might be confusing when writing references to those macros.
> 
> Since function-like macros internally are functions in the c-domain, 
> they are referred with ":c:func:`BAR`". On the other side, object-like
> macros are referred by role ":c:macro:`FOO`".
> 
> Taking this into account, it might be one reason more to follow
> your conclusion that functions and function-like macros are 
> interchangeable from the user's perspective.

It is not uncommon to "promote" some such macros to inline
functions, in order to have a stronger type check, or to do the
reverse, when we need a more generic declaration that would work
for multiple types.

So, keeping both macro function-like functions and functions using
the :c:function: seems to be the best, IMHO. It also makes life
easier for kernel-doc script.

> 
> -- Markus --
> 
> > 
> > BR,
> > Jani.
> > 
> > 
> > -- 
> > Jani Nikula, Intel Open Source Technology Center
> > --
> > To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> > the body of a message to majordomo@vger.kernel.org
> > More majordomo info at  http://vger.kernel.org/majordomo-info.html  
> 



Thanks,
Mauro

Re: [PATCH v3] docs-rst: ignore arguments on macro definitions

[Markus Heiser]

Am 31.08.2016 um 12:26 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:

> Em Wed, 31 Aug 2016 12:09:39 +0200
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
> 
>> Am 31.08.2016 um 11:02 schrieb Jani Nikula <jani.nikula@linux.intel.com>:
>> 
>>> On Wed, 31 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:  
>>>> I haven't tested your suggestion, but since *void* is in the list
>>>> of stop-words:
>>>> 
>>>>   # These C types aren't described anywhere, so don't try to create
>>>>   # a cross-reference to them
>>>>   stopwords = set((
>>>>       'const', 'void', 'char', 'wchar_t', 'int', 'short',
>>>>       'long', 'float', 'double', 'unsigned', 'signed', 'FILE',
>>>>       'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t',
>>>>       'struct', '_Bool',
>>>>   ))
>>>> 
>>>> I think it will work in the matter you think. 
>>>> 
>>>> However I like to prefer to fix it in the C-domain, using
>>>> Mauro's suggestion on argument parsing. IMHO it is not
>>>> the best solution to add a void type to the reST signature
>>>> of a macro. This will result in a unusual output and does
>>>> not fix what is wrong in Sphinx's c-domain (there is also
>>>> a drawback in the index, where a function-type macro is
>>>> referred as function, not as macro).  
>>> 
>>> From an API user's perspective, functions and function-like macros
>>> should work interchangeably.  
>> 
>> Ah, OK.
>> 
>>> Personally, I don't think there needs to be
>>> a difference in the index. This seems to be the approach taken in
>>> Sphinx, but it just doesn't work well for automatic documentation
>>> generation because we can't deduce the parameter types from the macro
>>> definition.  
>> 
>> In the index, sphinx refers only object-like macros with an entry 
>> "FOO (C macro))". Function-like macros are referred as "BAR (C function)".
>> 
>> I thought it is more straight forward to refer all macros with a 
>> "BAR (C macro)" entry in the index. I will split this change in
>> a separate patch, so we can decide if we like to patch the index
>> that way.
>> 
>> But now, as we discuss this, I have another doubt to fix the index.
>> It might be confusing when writing references to those macros.
>> 
>> Since function-like macros internally are functions in the c-domain, 
>> they are referred with ":c:func:`BAR`". On the other side, object-like
>> macros are referred by role ":c:macro:`FOO`".
>> 
>> Taking this into account, it might be one reason more to follow
>> your conclusion that functions and function-like macros are 
>> interchangeable from the user's perspective.
> 
> It is not uncommon to "promote" some such macros to inline
> functions, in order to have a stronger type check, or to do the
> reverse, when we need a more generic declaration that would work
> for multiple types.
> 
> So, keeping both macro function-like functions and functions using
> the :c:function: seems to be the best, IMHO. It also makes life
> easier for kernel-doc script.


May, I was unclear. I don't want to change the behavior: """keeping both
macro function-like functions and functions using the :c:function:""". 

The only thing I thought to change is, how the index entry will be. 
First I thought it might be more straight forward to refer func-like 
as "BAR (C macro)". But after Jani's conclusion, I had a doubt if
this is really a better entry in the index, than that what sphinx
already does "BAR (C function)".

Sorry for the confusion.

-- Markus --

Re: [PATCH v3] docs-rst: ignore arguments on macro definitions

[Mauro Carvalho Chehab]

Hi Jon/Markus,

Em Mon, 29 Aug 2016 16:12:39 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 
> > A macro definition is mapped via .. c:function:: at the
> > ReST markup when using the following kernel-doc tag:
> > 
> > 	/**
> > 	 * DMX_FE_ENTRY - Casts elements in the list of registered
> > 	 *               front-ends from the generic type struct list_head
> > 	 *               to the type * struct dmx_frontend
> > 	 *
> > 	 * @list: list of struct dmx_frontend
> > 	 */
> > 	 #define DMX_FE_ENTRY(list) \
> > 	        list_entry(list, struct dmx_frontend, connectivity_list)
> > 
> > However, unlike a function description, the arguments of a macro
> > doesn't contain the data type.
> > 
> > This causes warnings when enabling Sphinx on nitkpick mode,
> > like this one:
> > 	./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not found: list  
> 
> I think this is a drawback of sphinx's C-domain, using function
> definition for macros also. From the function documentation
> 
>  """This is also used to describe function-like preprocessor
>     macros. The names of the arguments should be given so
>     they may be used in the description."""
> 
> I think about to fix the nitpick message for macros (aka function
> directive) in the C-domain extension (we already have).
> 
> But for this, I need a rule to distinguish between macros
> and functions ... is the uppercase of the macro name a good
> rule to suppress the nitpick message? Any other suggestions?

What's the status of the C domain patches meant to fix this issue?

I managed to fix most warnings on media documents on nitpick mode.
With this patch applied, there are only 21 warnings (and all are
due to the lack of function or struct documentation). I'm about
to patchbomb such fixup series.

Yet, without  this patch, and latest docs-next, there are 20 extra
bogus warnings, due to function parameters:

 ./drivers/media/dvb-core/dvb_ringbuffer.h:121: WARNING: c:type reference target not found: rbuf
 ./drivers/media/dvb-core/dvb_ringbuffer.h:121: WARNING: c:type reference target not found: offs
 ./drivers/media/dvb-core/dvb_ringbuffer.h:130: WARNING: c:type reference target not found: rbuf
 ./drivers/media/dvb-core/dvb_ringbuffer.h:130: WARNING: c:type reference target not found: num
 ./drivers/media/dvb-core/dvb_ringbuffer.h:173: WARNING: c:type reference target not found: rbuf
 ./drivers/media/dvb-core/dvb_ringbuffer.h:173: WARNING: c:type reference target not found: byte
 ./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not found: list
 ./include/media/media-device.h:263: WARNING: c:type reference target not found: mdev
 ./include/media/media-device.h:495: WARNING: c:type reference target not found: mdev
 ./include/media/media-device.h:495: WARNING: c:type reference target not found: udev
 ./include/media/media-device.h:495: WARNING: c:type reference target not found: name
 ./include/media/media-entity.h:527: WARNING: c:type reference target not found: gobj
 ./include/media/media-entity.h:536: WARNING: c:type reference target not found: gobj
 ./include/media/media-entity.h:545: WARNING: c:type reference target not found: gobj
 ./include/media/media-entity.h:554: WARNING: c:type reference target not found: gobj
 ./include/media/media-entity.h:563: WARNING: c:type reference target not found: intf
 ./include/media/media-entity.h:1041: WARNING: c:type reference target not found: entity
 ./include/media/media-entity.h:1041: WARNING: c:type reference target not found: operation
 ./include/media/v4l2-ctrls.h:397: WARNING: c:type reference target not found: hdl
 ./include/media/v4l2-ctrls.h:397: WARNING: c:type reference target not found: nr_of_controls_hint

So, it would be great if we could either merge this patch or the ones that
Markus did (assuming they're ready for merge).

Regards,
Mauro

> 
> -- Markus --
> 
> > 
> > That happens because kernel-doc output for the above is:
> > 
> > 	.. c:function:: DMX_FE_ENTRY ( list)
> > 
> > 	   Casts elements in the list of registered front-ends from the generic type struct list_head to the type * struct dmx_frontend
> > 
> > 	**Parameters**
> > 
> > 	``list``
> > 	  list of struct dmx_frontend
> > 
> > As the type is blank, Sphinx would think that ``list`` is a type,
> > and will try to add a cross reference for it, using their internal
> > representation for c:type:`list`.
> > 
> > However, ``list`` is not a type. So, that would cause either the
> > above warning, or if a ``list`` type exists, it would create
> > a reference to the wrong place at the doc.
> > 
> > To avoid that, let's ommit macro arguments from c:function::
> > declaration. As each argument will appear below the Parameters,
> > the type of the argument can be described there, if needed.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> > 
> > v3: version 2 patch caused a regression when handling function arguments,
> > because the counter were not incremented on all cases. Fix it.
> > 
> > scripts/kernel-doc | 5 +++--
> > 1 file changed, 3 insertions(+), 2 deletions(-)
> > 
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index d225e178aa1b..bac0af4fc659 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -1846,14 +1846,15 @@ sub output_function_rst(%) {
> > 	if ($count ne 0) {
> > 	    print ", ";
> > 	}
> > -	$count++;
> > 	$type = $args{'parametertypes'}{$parameter};
> > 
> > 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
> > 	    # pointer-to-function
> > 	    print $1 . $parameter . ") (" . $2;
> > -	} else {
> > +	    $count++;
> > +	} elsif ($type ne "") {
> > 	    print $type . " " . $parameter;
> > +	    $count++;
> > 	}
> >    }
> >    print ")\n\n";
> > -- 
> > 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  
> 



Thanks,
Mauro

Re: [PATCH v3] docs-rst: ignore arguments on macro definitions

[Markus Heiser]

Am 08.09.2016 um 13:40 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:

> Hi Jon/Markus,
> 
> Em Mon, 29 Aug 2016 16:12:39 +0200
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
> 
>> Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>> 
>>> A macro definition is mapped via .. c:function:: at the
>>> ReST markup when using the following kernel-doc tag:
>>> 
>>> 	/**
>>> 	 * DMX_FE_ENTRY - Casts elements in the list of registered
>>> 	 *               front-ends from the generic type struct list_head
>>> 	 *               to the type * struct dmx_frontend
>>> 	 *
>>> 	 * @list: list of struct dmx_frontend
>>> 	 */
>>> 	 #define DMX_FE_ENTRY(list) \
>>> 	        list_entry(list, struct dmx_frontend, connectivity_list)
>>> 
>>> However, unlike a function description, the arguments of a macro
>>> doesn't contain the data type.
>>> 
>>> This causes warnings when enabling Sphinx on nitkpick mode,
>>> like this one:
>>> 	./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not found: list  
>> 
>> I think this is a drawback of sphinx's C-domain, using function
>> definition for macros also. From the function documentation
>> 
>> """This is also used to describe function-like preprocessor
>>    macros. The names of the arguments should be given so
>>    they may be used in the description."""
>> 
>> I think about to fix the nitpick message for macros (aka function
>> directive) in the C-domain extension (we already have).
>> 
>> But for this, I need a rule to distinguish between macros
>> and functions ... is the uppercase of the macro name a good
>> rule to suppress the nitpick message? Any other suggestions?
> 
> What's the status of the C domain patches meant to fix this issue?
> 
> I managed to fix most warnings on media documents on nitpick mode.
> With this patch applied, there are only 21 warnings (and all are
> due to the lack of function or struct documentation). I'm about
> to patchbomb such fixup series.
> 
> Yet, without  this patch, and latest docs-next, there are 20 extra
> bogus warnings, due to function parameters:
> 
> ./drivers/media/dvb-core/dvb_ringbuffer.h:121: WARNING: c:type reference target not found: rbuf
> ./drivers/media/dvb-core/dvb_ringbuffer.h:121: WARNING: c:type reference target not found: offs
> ./drivers/media/dvb-core/dvb_ringbuffer.h:130: WARNING: c:type reference target not found: rbuf
> ./drivers/media/dvb-core/dvb_ringbuffer.h:130: WARNING: c:type reference target not found: num
> ./drivers/media/dvb-core/dvb_ringbuffer.h:173: WARNING: c:type reference target not found: rbuf
> ./drivers/media/dvb-core/dvb_ringbuffer.h:173: WARNING: c:type reference target not found: byte
> ./drivers/media/dvb-core/demux.h:358: WARNING: c:type reference target not found: list
> ./include/media/media-device.h:263: WARNING: c:type reference target not found: mdev
> ./include/media/media-device.h:495: WARNING: c:type reference target not found: mdev
> ./include/media/media-device.h:495: WARNING: c:type reference target not found: udev
> ./include/media/media-device.h:495: WARNING: c:type reference target not found: name
> ./include/media/media-entity.h:527: WARNING: c:type reference target not found: gobj
> ./include/media/media-entity.h:536: WARNING: c:type reference target not found: gobj
> ./include/media/media-entity.h:545: WARNING: c:type reference target not found: gobj
> ./include/media/media-entity.h:554: WARNING: c:type reference target not found: gobj
> ./include/media/media-entity.h:563: WARNING: c:type reference target not found: intf
> ./include/media/media-entity.h:1041: WARNING: c:type reference target not found: entity
> ./include/media/media-entity.h:1041: WARNING: c:type reference target not found: operation
> ./include/media/v4l2-ctrls.h:397: WARNING: c:type reference target not found: hdl
> ./include/media/v4l2-ctrls.h:397: WARNING: c:type reference target not found: nr_of_controls_hint
> 
> So, it would be great if we could either merge this patch or the ones that
> Markus did (assuming they're ready for merge).

I fixed the remarks of Jon and resend v2 yesterday ...

https://www.mail-archive.com/linux-media@vger.kernel.org/msg102259.html

sorry, I'am currently in a hurry, may do you like to test the
patch, to see if we get rid of those 20 extra bogus warnings?

Thanks!

-- Markus --