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