From a2dace23aea60aaaf4cc10f8cdb8b1b33adc7adf Mon Sep 17 00:00:00 2001 From: Marius Vlad Date: Wed, 12 Jun 2019 16:05:44 +0300 Subject: [PATCH] libweston: Fix/clean-up doxygen warnings This fixes warnings for weston-debug, input, compositor, log and linux-explicit-sync. Warnings range from swapping '[in]', '[out]' with the function arguments to wrong parameter names. Signed-off-by: Marius Vlad --- libweston/backend-drm/drm.c | 15 +++++----- libweston/compositor.c | 32 ++++++++++++---------- libweston/input.c | 10 +++---- libweston/linux-explicit-synchronization.c | 2 +- libweston/log.c | 2 +- libweston/renderer-gl/gl-renderer.c | 2 +- libweston/weston-debug.c | 16 +++++------ 7 files changed, 40 insertions(+), 39 deletions(-) diff --git a/libweston/backend-drm/drm.c b/libweston/backend-drm/drm.c index 1ad23be7..311282ab 100644 --- a/libweston/backend-drm/drm.c +++ b/libweston/backend-drm/drm.c @@ -5272,9 +5272,9 @@ edid_parse(struct drm_edid *edid, const uint8_t *data, size_t length) * * \param head The head whose \c drm_edid to fill in. * \param props The DRM connector properties to get the EDID from. - * \param make[out] The monitor make (PNP ID). - * \param model[out] The monitor model (name). - * \param serial_number[out] The monitor serial number. + * \param[out] make The monitor make (PNP ID). + * \param[out] model The monitor model (name). + * \param[out] serial_number The monitor serial number. * * Each of \c *make, \c *model and \c *serial_number are set only if the * information is found in the EDID. The pointers they are set to must not @@ -5602,12 +5602,11 @@ drm_output_update_modelist_from_heads(struct drm_output *output) * Find the most suitable mode to use for initial setup (or reconfiguration on * hotplug etc) for a DRM output. * + * @param backend the DRM backend * @param output DRM output to choose mode for - * @param kind Strategy and preference to use when choosing mode - * @param width Desired width for this output - * @param height Desired height for this output - * @param current_mode Mode currently being displayed on this output + * @param mode Strategy and preference to use when choosing mode * @param modeline Manually-entered mode (may be NULL) + * @param current_mode Mode currently being displayed on this output * @returns A mode from the output's mode list, or NULL if none available */ static struct drm_mode * @@ -6389,7 +6388,7 @@ drm_head_update_info(struct drm_head *head) * Given a DRM connector, create a matching drm_head structure and add it * to Weston's head list. * - * @param b Weston backend structure + * @param backend Weston backend structure * @param connector_id DRM connector ID for the head * @param drm_device udev device pointer * @returns The new head, or NULL on failure. diff --git a/libweston/compositor.c b/libweston/compositor.c index fa2645fe..2e72513f 100644 --- a/libweston/compositor.c +++ b/libweston/compositor.c @@ -890,8 +890,8 @@ weston_surface_to_buffer_rect(struct weston_surface *surface, * * \param surface The surface to fetch wp_viewport and buffer transformation * from. - * \param surface_region[in] The region in surface coordinates. - * \param buffer_region[out] The region converted to buffer coordinates. + * \param[in] surface_region The region in surface coordinates. + * \param[out] buffer_region The region converted to buffer coordinates. * * Buffer_region must be init'd, but will be completely overwritten. * @@ -899,6 +899,7 @@ weston_surface_to_buffer_rect(struct weston_surface *surface, * and rotations in 90-degree steps. Therefore the only loss in the * conversion is from the coordinate rounding that takes place in * \ref weston_surface_to_buffer_rect. + * */ WL_EXPORT void weston_surface_to_buffer_region(struct weston_surface *surface, @@ -971,7 +972,7 @@ weston_view_damage_below(struct weston_view *view) * \param surface The surface. * \param head A head of the entered/left output. * \param enter True if entered. - * \param left True if left. + * \param leave True if left. * * Send the enter/leave events for all protocol objects bound to the given * output by the client owning the surface. @@ -4789,7 +4790,7 @@ weston_compositor_add_head(struct weston_compositor *compositor, * \param compositor The compositor. * \param listener The listener to add. * - * The listener notify function argument is the \var compositor. + * The listener notify function argument is weston_compositor. * * The listener function will be called after heads are added or their * connection status has changed. Several changes may be accumulated into a @@ -4810,7 +4811,7 @@ weston_compositor_add_heads_changed_listener(struct weston_compositor *composito /** Iterate over available heads * * \param compositor The compositor. - * \param item The iterator, or NULL for start. + * \param iter The iterator, or NULL for start. * \return The next available head in the list. * * Returns all available heads, regardless of being connected or enabled. @@ -4856,7 +4857,7 @@ weston_compositor_iterate_heads(struct weston_compositor *compositor, /** Iterate over attached heads * * \param output The output whose heads to iterate. - * \param item The iterator, or NULL for start. + * \param iter The iterator, or NULL for start. * \return The next attached head in the list. * * Returns all heads currently attached to the output. @@ -5564,14 +5565,15 @@ weston_compositor_add_output(struct weston_compositor *compositor, /** Transform device coordinates into global coordinates * - * \param device_x[in] X coordinate in device units. - * \param device_y[in] Y coordinate in device units. - * \param x[out] X coordinate in the global space. - * \param y[out] Y coordinate in the global space. + * \param output the weston_output object + * \param[in] device_x X coordinate in device units. + * \param[in] device_y Y coordinate in device units. + * \param[out] x X coordinate in the global space. + * \param[out] y Y coordinate in the global space. * - * Transforms coordinates from the device coordinate space - * (physical pixel units) to the global coordinate space (logical pixel units). - * This takes into account output transform and scale. + * Transforms coordinates from the device coordinate space (physical pixel + * units) to the global coordinate space (logical pixel units). This takes + * into account output transform and scale. * * \memberof weston_output * \internal @@ -6782,7 +6784,7 @@ debug_scene_graph_cb(struct weston_debug_stream *stream, void *data) * * \param display The Wayland display to be used. * \param user_data A pointer to an object that can later be retrieved - * \param wdc A pointer to weston_debug_compositor + * \param log_ctx A pointer to weston_debug_compositor * using the \ref weston_compositor_get_user_data function. * \return The compositor instance on success or NULL on failure. */ @@ -6999,7 +7001,7 @@ weston_compositor_set_presentation_clock_software( /** Read the current time from the Presentation clock * * \param compositor - * \param ts[out] The current time. + * \param[out] ts The current time. * * \note Reading the current time in user space is always imprecise to some * degree. diff --git a/libweston/input.c b/libweston/input.c index 9ecee4b1..99c39f7c 100644 --- a/libweston/input.c +++ b/libweston/input.c @@ -582,7 +582,7 @@ weston_pointer_has_focus_resource(struct weston_pointer *pointer) * \param pointer The pointer where the button events originates from. * \param time The timestamp of the event * \param button The button value of the event - * \param value The state enum value of the event + * \param state The state enum value of the event * * For every resource that is currently in focus, send a wl_pointer.button event * with the passed parameters. The focused resources are the wl_pointer @@ -639,8 +639,7 @@ default_grab_pointer_button(struct weston_pointer_grab *grab, * * \param pointer The pointer where the axis events originates from. * \param time The timestamp of the event - * \param axis The axis enum value of the event - * \param value The axis value of the event + * \param event The axis value of the event * * For every resource that is currently in focus, send a wl_pointer.axis event * with the passed parameters. The focused resources are the wl_pointer @@ -2541,8 +2540,8 @@ weston_compositor_set_touch_mode_calib(struct weston_compositor *compositor) * \param device The physical device that generated the event. * \param time The event timestamp. * \param touch_id ID for the touch point of this event (multi-touch). - * \param double_x X coordinate in compositor global space. - * \param double_y Y coordinate in compositor global space. + * \param x X coordinate in compositor global space. + * \param y Y coordinate in compositor global space. * \param norm Normalized device X, Y coordinates in calibration space, or NULL. * \param touch_type Either WL_TOUCH_DOWN, WL_TOUCH_UP, or WL_TOUCH_MOTION. * @@ -3621,6 +3620,7 @@ weston_seat_get_touch(struct weston_seat *seat) /** Sets the keyboard focus to the given surface * + * \param surface the surface to focus on * \param seat The seat to query */ WL_EXPORT void diff --git a/libweston/linux-explicit-synchronization.c b/libweston/linux-explicit-synchronization.c index ec2f015e..220cdde5 100644 --- a/libweston/linux-explicit-synchronization.c +++ b/libweston/linux-explicit-synchronization.c @@ -267,7 +267,7 @@ linux_explicit_synchronization_setup(struct weston_compositor *compositor) * * The error is sent as an INVALID_OBJECT error on the client's wl_display. * - * \param sync The explicit synchronization related resource that is unusable. + * \param resource The explicit synchronization related resource that is unusable. * \param msg A custom error message attached to the protocol error. */ WL_EXPORT void diff --git a/libweston/log.c b/libweston/log.c index 6b9840de..ed63de54 100644 --- a/libweston/log.c +++ b/libweston/log.c @@ -50,7 +50,7 @@ static log_func_t log_continue_handler = default_log_handler; * immediately aborted after the reminder is printed. * * \param fmt The format string. Ignored. - * \param va The variadic argument list. Ignored. + * \param ap The variadic argument list. Ignored. */ static int default_log_handler(const char *fmt, va_list ap) diff --git a/libweston/renderer-gl/gl-renderer.c b/libweston/renderer-gl/gl-renderer.c index d160a5d8..ce90ad3e 100644 --- a/libweston/renderer-gl/gl-renderer.c +++ b/libweston/renderer-gl/gl-renderer.c @@ -3504,7 +3504,7 @@ static const EGLint gl_renderer_alpha_attribs[] = { * by EGL. * * The extension suffix should be the suffix of the platform extension (that - * specifies a argument as defined in EGL_EXT_platform_base). For + * specifies a platform argument as defined in EGL_EXT_platform_base). For * example, passing "foo" will check whether either "EGL_KHR_platform_foo", * "EGL_EXT_platform_foo", or "EGL_MESA_platform_foo" is supported. * diff --git a/libweston/weston-debug.c b/libweston/weston-debug.c index 5f505346..8dcd880e 100644 --- a/libweston/weston-debug.c +++ b/libweston/weston-debug.c @@ -272,10 +272,10 @@ weston_log_ctx_compositor_setup(struct weston_compositor *compositor, return 0; } -/** Initialize weston_log_context structure +/** Creates weston_log_context structure * - * \param compositor The libweston compositor. - * \return 0 on success, -1 on failure. + * \return NULL in case of failure, or a weston_log_context object in case of + * success * * weston_log_context is a singleton for each weston_compositor. * @@ -372,7 +372,7 @@ weston_compositor_is_debug_protocol_enabled(struct weston_compositor *wc) * * \param log_ctx The weston_log_context where to add. * \param name The debug stream/scope name; must not be NULL. - * \param desc The debug scope description for humans; must not be NULL. + * \param description The debug scope description for humans; must not be NULL. * \param begin_cb Optional callback when a client subscribes to this scope. * \param user_data Optional user data pointer for the callback. * \return A valid pointer on success, NULL on failure. @@ -518,7 +518,7 @@ weston_log_scope_is_enabled(struct weston_log_scope *scope) /** Write data into a specific debug stream * * \param stream The debug stream to write into; must not be NULL. - * \param data[in] Pointer to the data to write. + * \param[in] data Pointer to the data to write. * \param len Number of bytes to write. * * Writes the given data (binary verbatim) into the debug stream. @@ -627,7 +627,7 @@ weston_debug_stream_complete(struct weston_debug_stream *stream) * * \param scope The debug scope to write for; may be NULL, in which case * nothing will be written. - * \param data[in] Pointer to the data to write. + * \param[in] data Pointer to the data to write. * \param len Number of bytes to write. * * Writes the given data to all subscribed clients' streams. @@ -710,8 +710,8 @@ weston_log_scope_printf(struct weston_log_scope *scope, /** Write debug scope name and current time into string * - * \param scope[in] debug scope; may be NULL - * \param buf[out] Buffer to store the string. + * \param[in] scope debug scope; may be NULL + * \param[out] buf Buffer to store the string. * \param len Available size in the buffer in bytes. * \return \c buf *