| Message ID | 20211007005305.15171-1-rdunlap@infradead.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [-next] drm/connector: fix all kernel-doc warnings | expand |
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
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.
--- 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
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(-)