[PATCH weston 05/15] libweston: two more weston_output docs

[Pekka Paalanen]

From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>

Document two more functions of the weston_output API.

Exported functions marked internal are meant for backends only.
Exported functions not marked internal are meant for libweston users.

Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
---
 libweston/compositor.c | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/libweston/compositor.c b/libweston/compositor.c
index 09a3db2..69e63c2 100644
--- a/libweston/compositor.c
+++ b/libweston/compositor.c
@@ -4466,6 +4466,8 @@ weston_output_move(struct weston_output *output, int x, int y)
  *
  * \param compositor The compositor instance.
  * \param output The output to be added.
+ *
+ * \internal
  */
 WL_EXPORT void
 weston_compositor_add_output(struct weston_compositor *compositor,
@@ -4482,6 +4484,20 @@ weston_compositor_add_output(struct weston_compositor *compositor,
 		weston_view_geometry_dirty(view);
 }
 
+/** 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.
+ *
+ * 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
+ */
 WL_EXPORT void
 weston_output_transform_coordinate(struct weston_output *output,
 				   double device_x, double device_y,
@@ -4543,6 +4559,9 @@ weston_output_enable_undo(struct weston_output *output)
  * are made inert.
  *
  * - The output is put back in the pending outputs list.
+ *
+ * \memberof weston_output
+ * \internal
  */
 static void
 weston_compositor_remove_output(struct weston_output *output)
@@ -4580,6 +4599,8 @@ weston_compositor_remove_output(struct weston_output *output)
  *
  * It only supports setting scale for an output that
  * is not enabled and it can only be ran once.
+ *
+ * \memberof weston_output
  */
 WL_EXPORT void
 weston_output_set_scale(struct weston_output *output,
@@ -4605,6 +4626,8 @@ weston_output_set_scale(struct weston_output *output,
  * Refer to wl_output::transform section located at
  * https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_output
  * for list of values that can be passed to this function.
+ *
+ * \memberof weston_output
  */
 WL_EXPORT void
 weston_output_set_transform(struct weston_output *output,
@@ -4627,6 +4650,9 @@ weston_output_set_transform(struct weston_output *output,
  *
  * Sets initial values for fields that are expected to be
  * configured either by compositors or backends.
+ *
+ * \memberof weston_output
+ * \internal
  */
 WL_EXPORT void
 weston_output_init(struct weston_output *output,
@@ -4661,6 +4687,9 @@ weston_output_init(struct weston_output *output,
  * configuration.
  *
  * The opposite of this operation is built into weston_output_destroy().
+ *
+ * \memberof weston_output
+ * \internal
  */
 WL_EXPORT void
 weston_compositor_add_pending_output(struct weston_output *output,
@@ -4835,6 +4864,17 @@ weston_pending_output_coldplug(struct weston_compositor *compositor)
 		wl_signal_emit(&compositor->output_pending_signal, output);
 }
 
+/** Uninitialize an output
+ *
+ * Removes the output from the live outputs list if necessary, but
+ * does not call the backend's output disable function.
+ *
+ * All fields of weston_output become uninitialized, i.e. should not be used
+ * anymore. The caller can free the memory after this.
+ *
+ * \memberof weston_output
+ * \internal
+ */
 WL_EXPORT void
 weston_output_destroy(struct weston_output *output)
 {
-- 
2.10.2