On Mon, 29 Aug 2016, Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> wrote: > Em Mon, 29 Aug 2016 16:12:39 +0200 > Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > >> Am 29.08.2016 um 15:13 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>: >> >> > 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@xxxxxxxxxxxxxxx > More majordomo info at http://vger.kernel.org/majordomo-info.html -- 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
