[PATCH -next] drm/connector: fix all kernel-doc warnings

[PATCH -next] drm/connector: fix all kernel-doc warnings

[Randy Dunlap]

Clean up all of the kernel-doc issues in drm_connector.c:

drivers/gpu/drm/drm_connector.c:2611: warning: Excess function parameter 'connector' description in 'drm_connector_oob_hotplug_event'
drivers/gpu/drm/drm_connector.c:2611: warning: Function parameter or member 'connector_fwnode' not described in 'drm_connector_oob_hotplug_event'

drm_connector.c:630: warning: No description found for return value of 'drm_get_connector_status_name'
drm_connector.c:715: warning: No description found for return value of 'drm_connector_list_iter_next'
drm_connector.c:785: warning: No description found for return value of 'drm_get_subpixel_order_name'
drm_connector.c:816: warning: No description found for return value of 'drm_display_info_set_bus_formats'
drm_connector.c:1331: warning: No description found for return value of 'drm_mode_create_dvi_i_properties'
drm_connector.c:1412: warning: No description found for return value of 'drm_connector_attach_content_type_property'
drm_connector.c:1492: warning: No description found for return value of 'drm_mode_create_tv_margin_properties'
drm_connector.c:1534: warning: No description found for return value of 'drm_mode_create_tv_properties'
drm_connector.c:1627: warning: No description found for return value of 'drm_mode_create_scaling_mode_property'
drm_connector.c:1944: warning: No description found for return value of 'drm_mode_create_suggested_offset_properties'

drm_connector.c:2315: warning: missing initial short description on line:
 * drm_connector_set_panel_orientation_with_quirk -

[The last warning listed is probably a quirk/bug in scripts/kernel-doc.]

Fixes: 613051dac40d ("drm: locking&new iterators for connector_list")
Fixes: 522171951761 ("drm: Extract drm_connector.[hc]")
Fixes: b3c6c8bfe378 ("drm: document drm_display_info")
Fixes: 50525c332b55 ("drm: content-type property for HDMI connector")
Fixes: 6c4f52dca36f ("drm/connector: Allow creation of margin props alone")
Fixes: 69654c632d80 ("drm/connector: Split out orientation quirk detection (v2)")
Fixes: 72ad49682dde ("drm/connector: Add support for out-of-band hotplug notification (v3)")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: David Airlie <airlied@linux.ie>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: dri-devel@lists.freedesktop.org
Cc: Stanislav Lisovskiy <stanislav.lisovskiy@intel.com>
Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
Cc: Boris Brezillon <boris.brezillon@bootlin.com>
Cc: Derek Basehore <dbasehore@chromium.org>
Cc: Hans de Goede <hdegoede@redhat.com>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <mripard@kernel.org>
Cc: Thomas Zimmermann <tzimmermann@suse.de>
---
72ad49682dde ("drm/connector: Add support for out-of-band hotplug notification (v3)")
  is only in linux-next. The others are in mainline.

 drivers/gpu/drm/drm_connector.c |   30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)

--- linux-next-20211006.orig/drivers/gpu/drm/drm_connector.c
+++ linux-next-20211006/drivers/gpu/drm/drm_connector.c
@@ -625,6 +625,8 @@ int drm_connector_register_all(struct dr
  *
  * In contrast to the other drm_get_*_name functions this one here returns a
  * const pointer and hence is threadsafe.
+ *
+ * Returns: connector status string
  */
 const char *drm_get_connector_status_name(enum drm_connector_status status)
 {
@@ -707,7 +709,7 @@ __drm_connector_put_safe(struct drm_conn
  * drm_connector_list_iter_next - return next connector
  * @iter: connector_list iterator
  *
- * Returns the next connector for @iter, or NULL when the list walk has
+ * Returns: the next connector for @iter, or NULL when the list walk has
  * completed.
  */
 struct drm_connector *
@@ -780,6 +782,8 @@ static const struct drm_prop_enum_list d
  *
  * Note you could abuse this and return something out of bounds, but that
  * would be a caller error.  No unscrubbed user data should make it here.
+ *
+ * Returns: string describing an enumerated subpixel property
  */
 const char *drm_get_subpixel_order_name(enum subpixel_order order)
 {
@@ -809,6 +813,9 @@ static const struct drm_prop_enum_list d
  * Store the supported bus formats in display info structure.
  * See MEDIA_BUS_FMT_* definitions in include/uapi/linux/media-bus-format.h for
  * a full list of available formats.
+ *
+ * Returns:
+ * Zero on success, negative errno on failure.
  */
 int drm_display_info_set_bus_formats(struct drm_display_info *info,
 				     const u32 *formats,
@@ -1326,6 +1333,8 @@ int drm_connector_create_standard_proper
  * @dev: DRM device
  *
  * Called by a driver the first time a DVI-I connector is made.
+ *
+ * Returns: %0
  */
 int drm_mode_create_dvi_i_properties(struct drm_device *dev)
 {
@@ -1407,6 +1416,8 @@ EXPORT_SYMBOL(drm_connector_attach_dp_su
  * @connector: connector to attach content type property on.
  *
  * Called by a driver the first time a HDMI connector is made.
+ *
+ * Returns: %0
  */
 int drm_connector_attach_content_type_property(struct drm_connector *connector)
 {
@@ -1487,6 +1498,9 @@ EXPORT_SYMBOL(drm_connector_attach_tv_ma
  * creates the TV margin properties for a given device. No need to call this
  * function for an SDTV connector, it's already called from
  * drm_mode_create_tv_properties().
+ *
+ * Returns:
+ * Zero on success, negative errno on failure.
  */
 int drm_mode_create_tv_margin_properties(struct drm_device *dev)
 {
@@ -1527,6 +1541,9 @@ EXPORT_SYMBOL(drm_mode_create_tv_margin_
  * the TV specific connector properties for a given device.  Caller is
  * responsible for allocating a list of format names and passing them to
  * this routine.
+ *
+ * Returns:
+ * Zero on success, negative errno on failure.
  */
 int drm_mode_create_tv_properties(struct drm_device *dev,
 				  unsigned int num_modes,
@@ -1622,6 +1639,8 @@ EXPORT_SYMBOL(drm_mode_create_tv_propert
  * Atomic drivers should use drm_connector_attach_scaling_mode_property()
  * instead to correctly assign &drm_connector_state.scaling_mode
  * in the atomic state.
+ *
+ * Returns: %0
  */
 int drm_mode_create_scaling_mode_property(struct drm_device *dev)
 {
@@ -1939,6 +1958,9 @@ EXPORT_SYMBOL(drm_mode_create_content_ty
  * @dev: DRM device
  *
  * Create the suggested x/y offset property for connectors.
+ *
+ * Returns:
+ * Zero on success, negative errno on failure.
  */
 int drm_mode_create_suggested_offset_properties(struct drm_device *dev)
 {
@@ -2312,8 +2334,8 @@ int drm_connector_set_panel_orientation(
 EXPORT_SYMBOL(drm_connector_set_panel_orientation);
 
 /**
- * drm_connector_set_panel_orientation_with_quirk -
- *	set the connector's panel_orientation after checking for quirks
+ * drm_connector_set_panel_orientation_with_quirk - set the
+ *	connector's panel_orientation after checking for quirks
  * @connector: connector for which to init the panel-orientation property.
  * @panel_orientation: drm_panel_orientation value to set
  * @width: width in pixels of the panel, used for panel quirk detection
@@ -2597,7 +2619,7 @@ struct drm_connector *drm_connector_find
 
 /**
  * drm_connector_oob_hotplug_event - Report out-of-band hotplug event to connector
- * @connector: connector to report the event on
+ * @connector_fwnode: fwnode_handle to report the event on
  *
  * On some hardware a hotplug event notification may come from outside the display
  * driver / device. An example of this is some USB Type-C setups where the hardware

Re: [PATCH -next] drm/connector: fix all kernel-doc warnings

[Sam Ravnborg]

Hi Randy,

I noticed a few things that in my opinion could be improved.
See below.

	Sam


On Wed, Oct 06, 2021 at 05:53:05PM -0700, Randy Dunlap wrote:
> Clean up all of the kernel-doc issues in drm_connector.c:
> 
> drivers/gpu/drm/drm_connector.c:2611: warning: Excess function parameter 'connector' description in 'drm_connector_oob_hotplug_event'
> drivers/gpu/drm/drm_connector.c:2611: warning: Function parameter or member 'connector_fwnode' not described in 'drm_connector_oob_hotplug_event'
> 
> drm_connector.c:630: warning: No description found for return value of 'drm_get_connector_status_name'
> drm_connector.c:715: warning: No description found for return value of 'drm_connector_list_iter_next'
> drm_connector.c:785: warning: No description found for return value of 'drm_get_subpixel_order_name'
> drm_connector.c:816: warning: No description found for return value of 'drm_display_info_set_bus_formats'
> drm_connector.c:1331: warning: No description found for return value of 'drm_mode_create_dvi_i_properties'
> drm_connector.c:1412: warning: No description found for return value of 'drm_connector_attach_content_type_property'
> drm_connector.c:1492: warning: No description found for return value of 'drm_mode_create_tv_margin_properties'
> drm_connector.c:1534: warning: No description found for return value of 'drm_mode_create_tv_properties'
> drm_connector.c:1627: warning: No description found for return value of 'drm_mode_create_scaling_mode_property'
> drm_connector.c:1944: warning: No description found for return value of 'drm_mode_create_suggested_offset_properties'
> 
> drm_connector.c:2315: warning: missing initial short description on line:
>  * drm_connector_set_panel_orientation_with_quirk -
> 
> [The last warning listed is probably a quirk/bug in scripts/kernel-doc.]
> 
> Fixes: 613051dac40d ("drm: locking&new iterators for connector_list")
> Fixes: 522171951761 ("drm: Extract drm_connector.[hc]")
> Fixes: b3c6c8bfe378 ("drm: document drm_display_info")
> Fixes: 50525c332b55 ("drm: content-type property for HDMI connector")
> Fixes: 6c4f52dca36f ("drm/connector: Allow creation of margin props alone")
> Fixes: 69654c632d80 ("drm/connector: Split out orientation quirk detection (v2)")
> Fixes: 72ad49682dde ("drm/connector: Add support for out-of-band hotplug notification (v3)")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: David Airlie <airlied@linux.ie>
> Cc: Daniel Vetter <daniel@ffwll.ch>
> Cc: dri-devel@lists.freedesktop.org
> Cc: Stanislav Lisovskiy <stanislav.lisovskiy@intel.com>
> Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
> Cc: Boris Brezillon <boris.brezillon@bootlin.com>
> Cc: Derek Basehore <dbasehore@chromium.org>
> Cc: Hans de Goede <hdegoede@redhat.com>
> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
> Cc: Maxime Ripard <mripard@kernel.org>
> Cc: Thomas Zimmermann <tzimmermann@suse.de>
> ---
> 72ad49682dde ("drm/connector: Add support for out-of-band hotplug notification (v3)")
>   is only in linux-next. The others are in mainline.
> 
>  drivers/gpu/drm/drm_connector.c |   30 ++++++++++++++++++++++++++----
>  1 file changed, 26 insertions(+), 4 deletions(-)
> 
> --- linux-next-20211006.orig/drivers/gpu/drm/drm_connector.c
> +++ linux-next-20211006/drivers/gpu/drm/drm_connector.c
> @@ -625,6 +625,8 @@ int drm_connector_register_all(struct dr
>   *
>   * In contrast to the other drm_get_*_name functions this one here returns a
>   * const pointer and hence is threadsafe.
> + *
> + * Returns: connector status string
>   */
>  const char *drm_get_connector_status_name(enum drm_connector_status status)
>  {
> @@ -707,7 +709,7 @@ __drm_connector_put_safe(struct drm_conn
>   * drm_connector_list_iter_next - return next connector
>   * @iter: connector_list iterator
>   *
> - * Returns the next connector for @iter, or NULL when the list walk has
> + * Returns: the next connector for @iter, or NULL when the list walk has
>   * completed.
>   */
>  struct drm_connector *
> @@ -780,6 +782,8 @@ static const struct drm_prop_enum_list d
>   *
>   * Note you could abuse this and return something out of bounds, but that
>   * would be a caller error.  No unscrubbed user data should make it here.
> + *
> + * Returns: string describing an enumerated subpixel property
>   */
>  const char *drm_get_subpixel_order_name(enum subpixel_order order)
>  {
> @@ -809,6 +813,9 @@ static const struct drm_prop_enum_list d
>   * Store the supported bus formats in display info structure.
>   * See MEDIA_BUS_FMT_* definitions in include/uapi/linux/media-bus-format.h for
>   * a full list of available formats.
> + *
> + * Returns:
> + * Zero on success, negative errno on failure.
I prefer the following variant:
"0 on success or a negative error code on failure."

Then we do not use the overloaded "errno" name.
At least in include/drm/* my preferred variant is the most popular for
what it is worth.

>   */
>  int drm_display_info_set_bus_formats(struct drm_display_info *info,
>  				     const u32 *formats,
> @@ -1326,6 +1333,8 @@ int drm_connector_create_standard_proper
>   * @dev: DRM device
>   *
>   * Called by a driver the first time a DVI-I connector is made.
> + *
> + * Returns: %0
Looks like some macro gone wrong - but I looked it up.
It is kernel-doc syntax for a named constant.

My personal preference would be a plain "0" - but that just
bikeshedding.


>   */
>  int drm_mode_create_dvi_i_properties(struct drm_device *dev)
>  {
> @@ -1407,6 +1416,8 @@ EXPORT_SYMBOL(drm_connector_attach_dp_su
>   * @connector: connector to attach content type property on.
>   *
>   * Called by a driver the first time a HDMI connector is made.
> + *
> + * Returns: %0
>   */
>  int drm_connector_attach_content_type_property(struct drm_connector *connector)
>  {
> @@ -1487,6 +1498,9 @@ EXPORT_SYMBOL(drm_connector_attach_tv_ma
>   * creates the TV margin properties for a given device. No need to call this
>   * function for an SDTV connector, it's already called from
>   * drm_mode_create_tv_properties().
> + *
> + * Returns:
> + * Zero on success, negative errno on failure.
>   */
>  int drm_mode_create_tv_margin_properties(struct drm_device *dev)
>  {
> @@ -1527,6 +1541,9 @@ EXPORT_SYMBOL(drm_mode_create_tv_margin_
>   * the TV specific connector properties for a given device.  Caller is
>   * responsible for allocating a list of format names and passing them to
>   * this routine.
> + *
> + * Returns:
> + * Zero on success, negative errno on failure.
>   */
>  int drm_mode_create_tv_properties(struct drm_device *dev,
>  				  unsigned int num_modes,
> @@ -1622,6 +1639,8 @@ EXPORT_SYMBOL(drm_mode_create_tv_propert
>   * Atomic drivers should use drm_connector_attach_scaling_mode_property()
>   * instead to correctly assign &drm_connector_state.scaling_mode
>   * in the atomic state.
> + *
> + * Returns: %0
>   */
>  int drm_mode_create_scaling_mode_property(struct drm_device *dev)
>  {
> @@ -1939,6 +1958,9 @@ EXPORT_SYMBOL(drm_mode_create_content_ty
>   * @dev: DRM device
>   *
>   * Create the suggested x/y offset property for connectors.
> + *
> + * Returns:
> + * Zero on success, negative errno on failure.
>   */
>  int drm_mode_create_suggested_offset_properties(struct drm_device *dev)
>  {
> @@ -2312,8 +2334,8 @@ int drm_connector_set_panel_orientation(
>  EXPORT_SYMBOL(drm_connector_set_panel_orientation);
>  
>  /**
> - * drm_connector_set_panel_orientation_with_quirk -
> - *	set the connector's panel_orientation after checking for quirks
> + * drm_connector_set_panel_orientation_with_quirk - set the
> + *	connector's panel_orientation after checking for quirks
>   * @connector: connector for which to init the panel-orientation property.
>   * @panel_orientation: drm_panel_orientation value to set
>   * @width: width in pixels of the panel, used for panel quirk detection
> @@ -2597,7 +2619,7 @@ struct drm_connector *drm_connector_find
>  
>  /**
>   * drm_connector_oob_hotplug_event - Report out-of-band hotplug event to connector
> - * @connector: connector to report the event on
> + * @connector_fwnode: fwnode_handle to report the event on
>   *
>   * On some hardware a hotplug event notification may come from outside the display
>   * driver / device. An example of this is some USB Type-C setups where the hardware

Re: [PATCH -next] drm/connector: fix all kernel-doc warnings

[Randy Dunlap]

Hi Sam,

On 10/10/21 1:04 PM, Sam Ravnborg wrote:
> Hi Randy,
> 
> I noticed a few things that in my opinion could be improved.
> See below.
> 
> 	Sam
> 
> 
> On Wed, Oct 06, 2021 at 05:53:05PM -0700, Randy Dunlap wrote:
>> Clean up all of the kernel-doc issues in drm_connector.c:
>>
>> drivers/gpu/drm/drm_connector.c:2611: warning: Excess function parameter 'connector' description in 'drm_connector_oob_hotplug_event'
>> drivers/gpu/drm/drm_connector.c:2611: warning: Function parameter or member 'connector_fwnode' not described in 'drm_connector_oob_hotplug_event'
>>
>> drm_connector.c:630: warning: No description found for return value of 'drm_get_connector_status_name'
>> drm_connector.c:715: warning: No description found for return value of 'drm_connector_list_iter_next'
>> drm_connector.c:785: warning: No description found for return value of 'drm_get_subpixel_order_name'
>> drm_connector.c:816: warning: No description found for return value of 'drm_display_info_set_bus_formats'
>> drm_connector.c:1331: warning: No description found for return value of 'drm_mode_create_dvi_i_properties'
>> drm_connector.c:1412: warning: No description found for return value of 'drm_connector_attach_content_type_property'
>> drm_connector.c:1492: warning: No description found for return value of 'drm_mode_create_tv_margin_properties'
>> drm_connector.c:1534: warning: No description found for return value of 'drm_mode_create_tv_properties'
>> drm_connector.c:1627: warning: No description found for return value of 'drm_mode_create_scaling_mode_property'
>> drm_connector.c:1944: warning: No description found for return value of 'drm_mode_create_suggested_offset_properties'
>>
>> drm_connector.c:2315: warning: missing initial short description on line:
>>   * drm_connector_set_panel_orientation_with_quirk -
>>
>> [The last warning listed is probably a quirk/bug in scripts/kernel-doc.]
>>
>> Fixes: 613051dac40d ("drm: locking&new iterators for connector_list")
>> Fixes: 522171951761 ("drm: Extract drm_connector.[hc]")
>> Fixes: b3c6c8bfe378 ("drm: document drm_display_info")
>> Fixes: 50525c332b55 ("drm: content-type property for HDMI connector")
>> Fixes: 6c4f52dca36f ("drm/connector: Allow creation of margin props alone")
>> Fixes: 69654c632d80 ("drm/connector: Split out orientation quirk detection (v2)")
>> Fixes: 72ad49682dde ("drm/connector: Add support for out-of-band hotplug notification (v3)")
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> Cc: David Airlie <airlied@linux.ie>
>> Cc: Daniel Vetter <daniel@ffwll.ch>
>> Cc: dri-devel@lists.freedesktop.org
>> Cc: Stanislav Lisovskiy <stanislav.lisovskiy@intel.com>
>> Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
>> Cc: Boris Brezillon <boris.brezillon@bootlin.com>
>> Cc: Derek Basehore <dbasehore@chromium.org>
>> Cc: Hans de Goede <hdegoede@redhat.com>
>> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
>> Cc: Maxime Ripard <mripard@kernel.org>
>> Cc: Thomas Zimmermann <tzimmermann@suse.de>
>> ---
>> 72ad49682dde ("drm/connector: Add support for out-of-band hotplug notification (v3)")
>>    is only in linux-next. The others are in mainline.
>>
>>   drivers/gpu/drm/drm_connector.c |   30 ++++++++++++++++++++++++++----
>>   1 file changed, 26 insertions(+), 4 deletions(-)
>>
>> --- linux-next-20211006.orig/drivers/gpu/drm/drm_connector.c
>> +++ linux-next-20211006/drivers/gpu/drm/drm_connector.c
>> @@ -625,6 +625,8 @@ int drm_connector_register_all(struct dr
>>    *
>>    * In contrast to the other drm_get_*_name functions this one here returns a
>>    * const pointer and hence is threadsafe.
>> + *
>> + * Returns: connector status string
>>    */
>>   const char *drm_get_connector_status_name(enum drm_connector_status status)
>>   {
>> @@ -707,7 +709,7 @@ __drm_connector_put_safe(struct drm_conn
>>    * drm_connector_list_iter_next - return next connector
>>    * @iter: connector_list iterator
>>    *
>> - * Returns the next connector for @iter, or NULL when the list walk has
>> + * Returns: the next connector for @iter, or NULL when the list walk has
>>    * completed.
>>    */
>>   struct drm_connector *
>> @@ -780,6 +782,8 @@ static const struct drm_prop_enum_list d
>>    *
>>    * Note you could abuse this and return something out of bounds, but that
>>    * would be a caller error.  No unscrubbed user data should make it here.
>> + *
>> + * Returns: string describing an enumerated subpixel property
>>    */
>>   const char *drm_get_subpixel_order_name(enum subpixel_order order)
>>   {
>> @@ -809,6 +813,9 @@ static const struct drm_prop_enum_list d
>>    * Store the supported bus formats in display info structure.
>>    * See MEDIA_BUS_FMT_* definitions in include/uapi/linux/media-bus-format.h for
>>    * a full list of available formats.
>> + *
>> + * Returns:
>> + * Zero on success, negative errno on failure.
> I prefer the following variant:
> "0 on success or a negative error code on failure."
> 
> Then we do not use the overloaded "errno" name.
> At least in include/drm/* my preferred variant is the most popular for
> what it is worth.

OK, I'll change it to that.

> 
>>    */
>>   int drm_display_info_set_bus_formats(struct drm_display_info *info,
>>   				     const u32 *formats,
>> @@ -1326,6 +1333,8 @@ int drm_connector_create_standard_proper
>>    * @dev: DRM device
>>    *
>>    * Called by a driver the first time a DVI-I connector is made.
>> + *
>> + * Returns: %0
> Looks like some macro gone wrong - but I looked it up.
> It is kernel-doc syntax for a named constant.
> 
> My personal preference would be a plain "0" - but that just
> bikeshedding.

Yeah, I would prefer to use kernel-doc notation for constants.
It is documented and has been around for a long time.

I will resend the patch.

Thanks.

-- 
~Randy