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 <marius.vlad@collabora.com>

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.

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.

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

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

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)

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 <platform> 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.
  *

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
  *