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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Am 08.09.2016 um 13:40 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:

> Hi Jon/Markus,
> 
> 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).
>> 
>> 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@xxxxxxxxxxxxxxx/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 --


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



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux