Am 09.09.2016 um 14:08 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx>: > Em Wed, 7 Sep 2016 09:12:55 +0200 > Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > >> From: Markus Heiser <markus.heiser@xxxxxxxxxxx> >> >> Hi Jon, >> >> according to your remarks I fixed the first and second patch. The third patch is >> resend unchanged; >> >>> Am 06.09.2016 um 14:28 schrieb Jonathan Corbet <corbet@xxxxxxx>: >>> >>> As others have pointed out, we generally want to hide the difference >>> between functions and macros, so this is probably one change we don't >>> want. >> >> I read "probably", so there might be a chance to persuade you ;) >> >> I'm not a friend of *information hiding* and since the index is sorted >> alphabetical it does no matter if the entry is 'FOO (C function)' or 'FOO (C >> macro)'. The last one has the right information e.g. for someone how is looking >> for a macro. FOO is a function-like macro and not a function, if the author >> describes the macro he might use the word "macro FOO" but in the index it is >> tagged as C function. >> >> Macros and functions are totally different even if their notation looks >> similarly. So where is the benefit of entries like 'FOO (C function)', which is >> IMHO ambiguous. >> >> I tagged the 'function-like macros index entry' patch with 'RFC' and resend it >> within this series. If you and/or others have a different opinion, feel free to >> drop it. >> >> Thanks for review. >> >> -- Markus -- >> >> >> Markus Heiser (3): >> doc-rst:c-domain: fix sphinx version incompatibility >> doc-rst:c-domain: function-like macros arguments >> doc-rst:c-domain: function-like macros index entry >> >> Documentation/sphinx/cdomain.py | 79 +++++++++++++++++++++++++++++++++++++++-- >> 1 file changed, 76 insertions(+), 3 deletions(-) >> > > Those patches indeed fix the issues. The arguments are now > processed properly. > > Tested-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> > > --- > > Using either this approach or my kernel-doc patch, I'm now getting > only two warnings: > > 1) at media-entity.h, even without nitpick mode: > > ./include/media/media-entity.h:1053: warning: No description found for parameter '...' > > This is caused by this kernel-doc tag and the corresponding macro: > > /** > * media_entity_call - Calls a struct media_entity_operations operation on > * an entity > * > * @entity: entity where the @operation will be called > * @operation: type of the operation. Should be the name of a member of > * struct &media_entity_operations. > * > * This helper function will check if @operation is not %NULL. On such case, > * it will issue a call to @operation\(@entity, @args\). > */ > > #define media_entity_call(entity, operation, args...) \ > (((entity)->ops && (entity)->ops->operation) ? \ > (entity)->ops->operation((entity) , ##args) : -ENOIOCTLCMD) > > > Basically, the Sphinx C domain seems to be expecting a description for > "...". I didn't find any way to get rid of that. > > 2) a nitpick warning at v4l2-mem2mem.h: > > ./include/media/v4l2-mem2mem.h:339: WARNING: c:type reference target not found: queue_init > > > /** > * v4l2_m2m_ctx_init() - allocate and initialize a m2m context > * > * @m2m_dev: opaque pointer to the internal data to handle M2M context > * @drv_priv: driver's instance private data > * @queue_init: a callback for queue type-specific initialization function > * to be used for initializing videobuf_queues > * > * Usually called from driver's ``open()`` function. > */ > struct v4l2_m2m_ctx *v4l2_m2m_ctx_init(struct v4l2_m2m_dev *m2m_dev, > void *drv_priv, > int (*queue_init)(void *priv, struct vb2_queue *src_vq, struct vb2_queue *dst_vq)); > > I checked the output of kernel-doc, and it looked ok. Yet, it expects > "queue_init" to be defined somehow. I suspect that this is an error at > Sphinx C domain parser. > > Markus, > > Could you please take a look on those? Yes, I will give it a try, but I don't know if I find the time today. On wich branch could I test this? -- Markus -- > > 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 -- 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
