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

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

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