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. 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
