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 <[email protected]> Cc: David Airlie <[email protected]> Cc: Daniel Vetter <[email protected]> Cc: [email protected] Cc: Stanislav Lisovskiy <[email protected]> Cc: Ville Syrjälä <[email protected]> Cc: Boris Brezillon <[email protected]> Cc: Derek Basehore <[email protected]> Cc: Hans de Goede <[email protected]> Cc: Maarten Lankhorst <[email protected]> Cc: Maxime Ripard <[email protected]> Cc: Thomas Zimmermann <[email protected]> --- 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: %0Looks 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
