diff mbox series

media: v4l2-common.h: kerneldoc: correctly format return values

Message ID d38e25c0-a508-46d9-97cd-a50d31483c82@xs4all.nl (mailing list archive)
State New, archived
Headers show
Series media: v4l2-common.h: kerneldoc: correctly format return values | expand

Commit Message

Hans Verkuil Feb. 2, 2024, 8:25 a.m. UTC 
Building the kerneldoc resulted in two errors:

Documentation/media/driver-api/v4l2-common:6: ./include/media/v4l2-common.h:566: ERROR: Unexpected indentation.
Documentation/media/driver-api/v4l2-common:6: ./include/media/v4l2-common.h:567: WARNING: Block quote ends without a blank line; unexpected unindent.

Format v4l2_link_freq_to_bitmap according to the kerneldoc standard.
The v4l2_fill_pixfmt_mp function also had incorrect return value formatting,
although that didn't report an error/warning, but it looked ugly in the
generated documentation. So fix that one as well.

Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Fixes: a68e88e2cf9e ("media: v4l: Add a helper for setting up link-frequencies control")
---

Comments

Sakari Ailus Feb. 2, 2024, 8:47 a.m. UTC | #1 
Hi Hans,

On Fri, Feb 02, 2024 at 09:25:44AM +0100, Hans Verkuil wrote:
> Building the kerneldoc resulted in two errors:
> 
> Documentation/media/driver-api/v4l2-common:6: ./include/media/v4l2-common.h:566: ERROR: Unexpected indentation.
> Documentation/media/driver-api/v4l2-common:6: ./include/media/v4l2-common.h:567: WARNING: Block quote ends without a blank line; unexpected unindent.
> 
> Format v4l2_link_freq_to_bitmap according to the kerneldoc standard.
> The v4l2_fill_pixfmt_mp function also had incorrect return value formatting,
> although that didn't report an error/warning, but it looked ugly in the
> generated documentation. So fix that one as well.
> 
> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
> Fixes: a68e88e2cf9e ("media: v4l: Add a helper for setting up link-frequencies control")

I wrote a patch to address these as well but I think yours is better.

Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
diff mbox series

Patch

diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
index cd2163f24f8a..ffed604bc29a 100644
--- a/include/media/v4l2-common.h
+++ b/include/media/v4l2-common.h
@@ -536,9 +536,10 @@  int v4l2_fill_pixfmt_mp(struct v4l2_pix_format_mplane *pixfmt, u32 pixelformat,
  * V4L2_CID_LINK_FREQ control implemented by the transmitter, or value
  * calculated based on the V4L2_CID_PIXEL_RATE implemented by the transmitter.
  *
- * Returns link frequency on success, otherwise a negative error code:
- *	-ENOENT: Link frequency or pixel rate control not found
- *	-EINVAL: Invalid link frequency value
+ * Return:
+ * * >0: Link frequency
+ * * %-ENOENT: Link frequency or pixel rate control not found
+ * * %-EINVAL: Invalid link frequency value
  */
 s64 v4l2_get_link_freq(struct v4l2_ctrl_handler *handler, unsigned int mul,
 		       unsigned int div);
@@ -560,11 +561,11 @@  u32 v4l2_fraction_to_interval(u32 numerator, u32 denominator);
  * system firmware and sets the corresponding bits in @bitmap (after first
  * zeroing it).
  *
- * Return values:
- *	0: Success
- *	-ENOENT: No match found between driver-supported link frequencies and
- *		 those available in firmware.
- *	-ENODATA: No link frequencies were specified in firmware.
+ * Return:
+ * * %0: Success
+ * * %-ENOENT: No match found between driver-supported link frequencies and
+ *   those available in firmware.
+ * * %-ENODATA: No link frequencies were specified in firmware.
  */
 int v4l2_link_freq_to_bitmap(struct device *dev, const u64 *fw_link_freqs,
 			     unsigned int num_of_fw_link_freqs,