From 5a8f098eea1637213d29a6ec831bcebc11c92aaa Mon Sep 17 00:00:00 2001
From: emersion <contact@emersion.fr>
Date: Sun, 11 Feb 2018 13:04:00 +0100
Subject: [PATCH] output, output_damage: add docs

---
 include/wlr/types/wlr_output.h        |  9 +++++++++
 include/wlr/types/wlr_output_damage.h | 28 +++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/include/wlr/types/wlr_output.h b/include/wlr/types/wlr_output.h
index a653d527..8eed06fe 100644
--- a/include/wlr/types/wlr_output.h
+++ b/include/wlr/types/wlr_output.h
@@ -38,6 +38,15 @@ struct wlr_output_cursor {
 
 struct wlr_output_impl;
 
+/**
+ * A compositor output region. This typically corresponds to a monitor that
+ * displays part of the compositor space.
+ *
+ * Compositors should listen to the `frame` event to render an output. They
+ * should call `wlr_output_make_current`, render and then call
+ * `wlr_output_swap_buffers`. No rendering should happen outside a `frame` event
+ * handler.
+ */
 struct wlr_output {
 	const struct wlr_output_impl *impl;
 	struct wlr_backend *backend;
diff --git a/include/wlr/types/wlr_output_damage.h b/include/wlr/types/wlr_output_damage.h
index eadbff29..ec5fcd0d 100644
--- a/include/wlr/types/wlr_output_damage.h
+++ b/include/wlr/types/wlr_output_damage.h
@@ -10,6 +10,14 @@
  */
 #define WLR_OUTPUT_DAMAGE_PREVIOUS_LEN 2
 
+/**
+ * Tracks damage for an output.
+ *
+ * When a `frame` event is emitted, `wlr_output_damage_make_current` should be
+ * called. If necessary, the output should be repainted and
+ * `wlr_output_damage_swap_buffers` should be called. No rendering should happen
+ * outside a `frame` event handler.
+ */
 struct wlr_output_damage {
 	struct wlr_output *output;
 
@@ -32,13 +40,33 @@ struct wlr_output_damage {
 
 struct wlr_output_damage *wlr_output_damage_create(struct wlr_output *output);
 void wlr_output_damage_destroy(struct wlr_output_damage *output_damage);
+/**
+ * Makes the output rendering context current. `needs_swap` is set to true if
+ * `wlr_output_damage_swap_buffers` needs to be called. The region of the output
+ * that needs to be repainted is added to `damage`.
+ */
 bool wlr_output_damage_make_current(struct wlr_output_damage *output_damage,
 	bool *needs_swap, pixman_region32_t *damage);
+/**
+ * Swaps the output buffers. If the time of the frame isn't known, set `when` to
+ * NULL.
+ *
+ * Swapping buffers schedules a `frame` event.
+ */
 bool wlr_output_damage_swap_buffers(struct wlr_output_damage *output_damage,
 	struct timespec *when, pixman_region32_t *damage);
+/**
+ * Accumulates damage and schedules a `frame` event.
+ */
 void wlr_output_damage_add(struct wlr_output_damage *output_damage,
 	pixman_region32_t *damage);
+/**
+ * Damages the whole output and schedules a `frame` event.
+ */
 void wlr_output_damage_add_whole(struct wlr_output_damage *output_damage);
+/**
+ * Accumulates damage from a box and schedules a `frame` event.
+ */
 void wlr_output_damage_add_box(struct wlr_output_damage *output_damage,
 	struct wlr_box *box);