Hi Mauro, 

sorry for my late reply (so much work to do) ..

Am 09.09.2016 um 14:25 schrieb Markus Heiser <markus.hei...@darmarit.de>:

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

FYI: This message comes from the kernel-doc parser.

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

This is a bug in the kernel-doc parser. The parser generates:

  .. c:function:: media_entity_call ( entity,  operation,  ...)

correct is:

  .. c:function::  media_entity_call( entity,  operation,  args...)

So both, the message and the wrong parse result comes from kernel-doc.

>> 
>> 2) a nitpick warning at v4l2-mem2mem.h:
>> 
>> ./include/media/v4l2-mem2mem.h:339: WARNING: c:type reference target not 
>> found: queue_init

FYI: this message comes from sphinx c-domain.

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

Hmm, as far as I see, the output is not correct ... The output of
functions with a function pointer argument are missing the 
leading parenthesis in the function definition:

  .. c: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)

The missing parenthesis cause the error message. 

The output of the parameter description is:

  ``int (*)(void *priv, struct vb2_queue *src_vq, struct vb2_queue *dst_vq) 
queue_init``
    a callback for queue type-specific initialization function
    to be used for initializing videobuf_queues

Correct (and IMO better to read) is:

  .. c: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))

and the parameter description should be something like ...

   :param int (\*queue_init)(void \*priv, struct vb2_queue \*src_vq, struct 
vb2_queue \*dst_vq):
        a callback for queue type-specific initialization function
        to be used for initializing videobuf_queues

I tested this with my linuxdoc tools (parser) with I get no
error messages from the sphinx c-domain.

BTW: 

The parser of my linuxdoc project is more strict and spit out some 
warnings, which are not detected by the kernel-doc parser from the
kernel source tree.

For your rework on kernel-doc comments, it might be helpful to see
those messages, so I recommend to install the linuxdoc package and
do some lint.

install: https://return42.github.io/linuxdoc/install.html
lint:    https://return42.github.io/linuxdoc/cmd-line.html#kernel-lintdoc

E.g. if you want to lint your whole include/media tree type:

  kernel-lintdoc [--sloppy] include/media


-- Markus --

>> 
>> 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-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to