[media] get rid of a number of problems at the cross references

mchehab · mchehab · commit e383ce0736f5 · 2016-09-22T10:00:23.000-03:00
As warned by linuxdoc[1] tool, using: $ for i in $(git grep kernel-doc Documentation/media/kapi/|cut -d: -f4); do kernel-lintdoc --sloppy $i; done include/media/v4l2-dev.h:118 :WARN: function name from comment differs: v4l2_prio_close <--> v4l2_prio_check include/media/v4l2-mc.h:56 [kernel-doc WARN] : enum name from comment differs: if_vid_dec_index <--> if_vid_dec_pad_index include/media/v4l2-mc.h:71 [kernel-doc WARN] : enum name from comment differs: if_aud_dec_index <--> if_aud_dec_pad_index include/media/v4l2-mem2mem.h:396 [kernel-doc WARN] : function name from comment differs: v4l2_m2m_num_src_bufs_ready <--> v4l2_m2m_num_dst_bufs_ready drivers/media/dvb-core/dvb_math.h:28 [kernel-doc WARN] : function name from comment differs: cintlog2 <--> intlog2 include/media/v4l2-subdev.h:215 [kernel-doc WARN] : struct name from comment differs: s_radio <--> v4l2_subdev_tuner_ops include/media/v4l2-subdev.h:890 [kernel-doc WARN] : function name from comment differs: v4l2_set_subdevdata <--> v4l2_set_subdev_hostdata include/media/v4l2-subdev.h:901 [kernel-doc WARN] : function name from comment differs: v4l2_get_subdevdata <--> v4l2_get_subdev_hostdata drivers/media/dvb-core/dvb_ringbuffer.h:196 [kernel-doc WARN] : function name from comment differs: dvb_ringbuffer_writeuser <--> dvb_ringbuffer_write_user include/media/videobuf2-core.h:399 [kernel-doc WARN] : struct name from comment differs: vb2_ops <--> vb2_buf_ops include/media/media-entity.h:132 [kernel-doc ERROR] : duplicate parameter definition 'source' include/media/media-entity.h:477 [kernel-doc WARN] : function name from comment differs: media_entity_enum_test <--> media_entity_enum_test_and_set include/media/media-entity.h:535 [kernel-doc WARN] : function name from comment differs: gobj_to_entity <--> gobj_to_pad include/media/media-entity.h:544 [kernel-doc WARN] : function name from comment differs: gobj_to_entity <--> gobj_to_link include/media/media-entity.h:553 [kernel-doc WARN] : function name from comment differs: gobj_to_entity <--> gobj_to_intf include/media/media-entity.h:562 [kernel-doc WARN] : function name from comment differs: gobj_to_entity <--> intf_to_devnode include/media/rc-core.h:234 [kernel-doc WARN] : function name from comment differs: rc_open <--> rc_close include/media/v4l2-ctrls.h:397 [kernel-doc WARN] : missing initial short description of 'v4l2_ctrl_handler_init' include/media/v4l2-dev.h:118 [kernel-doc WARN] : function name from comment differs: v4l2_prio_close <--> v4l2_prio_check include/media/v4l2-event.h:225 [kernel-doc WARN] : missing initial short description of 'v4l2_src_change_event_subscribe' [1] https://return42.github.io/linuxdoc/linux.html The above are real issues at the documentation. On several cases, caused by cut-and-paste. Fix them. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst
@@ -173,7 +173,7 @@ The implementation of a hotplug disconnect should also take the lock from
 using :c:type:`video_device`->queue->lock, then you have to first lock
 :c:type:`video_device`->queue->lock followed by :c:type:`video_device`->lock.
 That way you can be sure no ioctl is running when you call
-:c:type:`v4l2_device_disconnect`.
+:c:func:`v4l2_device_disconnect`.
 
 Video device registration
 -------------------------
diff --git a/drivers/media/dvb-core/dvb_math.h b/drivers/media/dvb-core/dvb_math.h
@@ -25,7 +25,7 @@
 #include <linux/types.h>
 
 /**
- * cintlog2 - computes log2 of a value; the result is shifted left by 24 bits
+ * intlog2 - computes log2 of a value; the result is shifted left by 24 bits
  *
  * @value: The value (must be != 0)
  *
diff --git a/drivers/media/dvb-core/dvb_ringbuffer.h b/drivers/media/dvb-core/dvb_ringbuffer.h
@@ -193,7 +193,7 @@ extern ssize_t dvb_ringbuffer_write(struct dvb_ringbuffer *rbuf, const u8 *buf,
 				    size_t len);
 
 /**
- * dvb_ringbuffer_writeuser - Writes a buffer received via an user pointer
+ * dvb_ringbuffer_write_user - Writes a buffer received via an user pointer
  *
  * @rbuf: pointer to struct dvb_ringbuffer
  * @buf: pointer to the buffer where the data will be read
diff --git a/include/media/media-entity.h b/include/media/media-entity.h
@@ -129,7 +129,7 @@ struct media_pipeline {
  *		an interface.
  * @gobj1:	Part of a union. Used to get the pointer for the second
  *		graph_object of the link.
- * @source:	Part of a union. Used only if the second object (gobj1) is
+ * @sink:	Part of a union. Used only if the second object (gobj1) is
  *		a pad. In that case, it represents the sink pad.
  * @entity:	Part of a union. Used only if the second object (gobj1) is
  *		an entity.
@@ -474,7 +474,8 @@ static inline bool media_entity_enum_test(struct media_entity_enum *ent_enum,
 }
 
 /**
- * media_entity_enum_test - Test whether the entity is marked, and mark it
+ * media_entity_enum_test_and_set - Test whether the entity is marked,
+ *	and mark it
  *
  * @ent_enum: Entity enumeration
  * @entity: Entity to be tested
@@ -532,7 +533,7 @@ static inline bool media_entity_enum_intersects(
 		container_of(gobj, struct media_entity, graph_obj)
 
 /**
- * gobj_to_entity - returns the struct &media_pad pointer from the
+ * gobj_to_pad - returns the struct &media_pad pointer from the
  *	@gobj contained on it.
  *
  * @gobj: Pointer to the struct &media_gobj graph object
@@ -541,7 +542,7 @@ static inline bool media_entity_enum_intersects(
 		container_of(gobj, struct media_pad, graph_obj)
 
 /**
- * gobj_to_entity - returns the struct &media_link pointer from the
+ * gobj_to_link - returns the struct &media_link pointer from the
  *	@gobj contained on it.
  *
  * @gobj: Pointer to the struct &media_gobj graph object
@@ -550,7 +551,7 @@ static inline bool media_entity_enum_intersects(
 		container_of(gobj, struct media_link, graph_obj)
 
 /**
- * gobj_to_entity - returns the struct &media_interface pointer from the
+ * gobj_to_intf - returns the struct &media_interface pointer from the
  *	@gobj contained on it.
  *
  * @gobj: Pointer to the struct &media_gobj graph object
@@ -559,7 +560,7 @@ static inline bool media_entity_enum_intersects(
 		container_of(gobj, struct media_interface, graph_obj)
 
 /**
- * gobj_to_entity - returns the struct media_intf_devnode pointer from the
+ * intf_to_devnode - returns the struct media_intf_devnode pointer from the
  *	@intf contained on it.
  *
  * @intf: Pointer to struct &media_intf_devnode
diff --git a/include/media/rc-core.h b/include/media/rc-core.h
@@ -231,7 +231,7 @@ void rc_unregister_device(struct rc_dev *dev);
 int rc_open(struct rc_dev *rdev);
 
 /**
- * rc_open - Closes a RC device
+ * rc_close - Closes a RC device
  *
  * @rdev: pointer to struct rc_dev.
  */
diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
@@ -394,7 +394,8 @@ int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
 #ifdef CONFIG_LOCKDEP
 
 /**
- * v4l2_ctrl_handler_init -
+ * v4l2_ctrl_handler_init - helper function to create a static struct
+ *	 &lock_class_key and calls v4l2_ctrl_handler_init_class()
  *
  * @hdl:	The control handler.
  * @nr_of_controls_hint: A hint of how many controls this handler is
diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
@@ -115,7 +115,7 @@ void v4l2_prio_close(struct v4l2_prio_state *global, enum v4l2_priority local);
 enum v4l2_priority v4l2_prio_max(struct v4l2_prio_state *global);
 
 /**
- * v4l2_prio_close - Implements the priority logic for a file handler close
+ * v4l2_prio_check - Implements the priority logic for a file handler close
  *
  * @global: pointer to the &struct v4l2_prio_state of the device node.
  * @local: desired priority, as defined by enum &v4l2_priority local
diff --git a/include/media/v4l2-event.h b/include/media/v4l2-event.h
@@ -222,7 +222,8 @@ int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd,
 				  struct v4l2_fh *fh,
 				  struct v4l2_event_subscription *sub);
 /**
- * v4l2_src_change_event_subscribe -
+ * v4l2_src_change_event_subscribe - helper function that calls
+ * 	v4l2_event_subscribe() if the event is %V4L2_EVENT_SOURCE_CHANGE.
  *
  * @fh: pointer to struct v4l2_fh
  * @sub: pointer to &struct v4l2_event_subscription
diff --git a/include/media/v4l2-mc.h b/include/media/v4l2-mc.h
@@ -53,7 +53,7 @@ enum tuner_pad_index {
 };
 
 /**
- * enum if_vid_dec_index - video IF-PLL pad index for
+ * enum if_vid_dec_pad_index - video IF-PLL pad index for
  *			   MEDIA_ENT_F_IF_VID_DECODER
  *
  * @IF_VID_DEC_PAD_IF_INPUT:	video Intermediate Frequency (IF) sink pad
@@ -68,7 +68,7 @@ enum if_vid_dec_pad_index {
 };
 
 /**
- * enum if_aud_dec_index - audio/sound IF-PLL pad index for
+ * enum if_aud_dec_pad_index - audio/sound IF-PLL pad index for
  *			   MEDIA_ENT_F_IF_AUD_DECODER
  *
  * @IF_AUD_DEC_PAD_IF_INPUT:	audio Intermediate Frequency (IF) sink pad
diff --git a/include/media/v4l2-mem2mem.h b/include/media/v4l2-mem2mem.h
@@ -393,7 +393,7 @@ unsigned int v4l2_m2m_num_src_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)
 }
 
 /**
- * v4l2_m2m_num_src_bufs_ready() - return the number of destination buffers
+ * v4l2_m2m_num_dst_bufs_ready() - return the number of destination buffers
  * ready for use
  *
  * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx
diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
@@ -212,7 +212,8 @@ struct v4l2_subdev_core_ops {
 };
 
 /**
- * struct s_radio - Callbacks used when v4l device was opened in radio mode.
+ * struct v4l2_subdev_tuner_ops - Callbacks used when v4l device was opened
+ *	in radio mode.
  *
  * @s_radio: callback for %VIDIOC_S_RADIO ioctl handler code.
  *
@@ -887,7 +888,7 @@ static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd)
 }
 
 /**
- * v4l2_set_subdevdata - Sets V4L2 dev private host data
+ * v4l2_set_subdev_hostdata - Sets V4L2 dev private host data
  *
  * @sd: pointer to &struct v4l2_subdev
  * @p: pointer to the private data to be stored.
@@ -898,7 +899,7 @@ static inline void v4l2_set_subdev_hostdata(struct v4l2_subdev *sd, void *p)
 }
 
 /**
- * v4l2_get_subdevdata - Gets V4L2 dev private data
+ * v4l2_get_subdev_hostdata - Gets V4L2 dev private data
  *
  * @sd: pointer to &struct v4l2_subdev
  *
diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
@@ -396,7 +396,7 @@ struct vb2_ops {
 };
 
 /**
- * struct vb2_ops - driver-specific callbacks
+ * struct vb2_buf_ops - driver-specific callbacks
  *
  * @verify_planes_array: Verify that a given user space structure contains
  *			enough planes for the buffer. This is called

Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,7 @@`
`25`	`25`	`#include <linux/types.h>`
`26`	`26`
`27`	`27`	`/**`
`28`		`- * cintlog2 - computes log2 of a value; the result is shifted left by 24 bits`
	`28`	`+ * intlog2 - computes log2 of a value; the result is shifted left by 24 bits`
`29`	`29`	`*`
`30`	`30`	`* @value: The value (must be != 0)`
`31`	`31`	`*`
Original file line number	Diff line number	Diff line change
`@@ -193,7 +193,7 @@ extern ssize_t dvb_ringbuffer_write(struct dvb_ringbuffer rbuf, const u8 buf,`
`193`	`193`	`size_t len);`
`194`	`194`
`195`	`195`	`/**`
`196`		`- * dvb_ringbuffer_writeuser - Writes a buffer received via an user pointer`
	`196`	`+ * dvb_ringbuffer_write_user - Writes a buffer received via an user pointer`
`197`	`197`	`*`
`198`	`198`	`* @rbuf: pointer to struct dvb_ringbuffer`
`199`	`199`	`* @buf: pointer to the buffer where the data will be read`
Original file line number	Diff line number	Diff line change
`@@ -231,7 +231,7 @@ void rc_unregister_device(struct rc_dev *dev);`
`231`	`231`	`int rc_open(struct rc_dev *rdev);`
`232`	`232`
`233`	`233`	`/**`
`234`		`- * rc_open - Closes a RC device`
	`234`	`+ * rc_close - Closes a RC device`
`235`	`235`	`*`
`236`	`236`	`* @rdev: pointer to struct rc_dev.`
`237`	`237`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -394,7 +394,8 @@ int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,`
`394`	`394`	`#ifdef CONFIG_LOCKDEP`
`395`	`395`
`396`	`396`	`/**`
`397`		`- * v4l2_ctrl_handler_init -`
	`397`	`+ * v4l2_ctrl_handler_init - helper function to create a static struct`
	`398`	`+ * &lock_class_key and calls v4l2_ctrl_handler_init_class()`
`398`	`399`	`*`
`399`	`400`	`* @hdl: The control handler.`
`400`	`401`	`* @nr_of_controls_hint: A hint of how many controls this handler is`
Original file line number	Diff line number	Diff line change
`@@ -115,7 +115,7 @@ void v4l2_prio_close(struct v4l2_prio_state *global, enum v4l2_priority local);`
`115`	`115`	`enum v4l2_priority v4l2_prio_max(struct v4l2_prio_state *global);`
`116`	`116`
`117`	`117`	`/**`
`118`		`- * v4l2_prio_close - Implements the priority logic for a file handler close`
	`118`	`+ * v4l2_prio_check - Implements the priority logic for a file handler close`
`119`	`119`	`*`
`120`	`120`	`* @global: pointer to the &struct v4l2_prio_state of the device node.`
`121`	`121`	`* @local: desired priority, as defined by enum &v4l2_priority local`
Original file line number	Diff line number	Diff line change
`@@ -393,7 +393,7 @@ unsigned int v4l2_m2m_num_src_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx)`
`393`	`393`	`}`
`394`	`394`
`395`	`395`	`/**`
`396`		`- * v4l2_m2m_num_src_bufs_ready() - return the number of destination buffers`
	`396`	`+ * v4l2_m2m_num_dst_bufs_ready() - return the number of destination buffers`
`397`	`397`	`* ready for use`
`398`	`398`	`*`
`399`	`399`	`* @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx`