From 7d24af43e5f2fc04b41c5697101a44d67a384a12 Mon Sep 17 00:00:00 2001
From: emersion <contact@emersion.fr>
Date: Fri, 8 Jun 2018 20:28:57 +0100
Subject: [PATCH] buffer: improve docs

---
 include/wlr/types/wlr_buffer.h | 38 ++++++++++++++++++++++++++--------
 1 file changed, 29 insertions(+), 9 deletions(-)

diff --git a/include/wlr/types/wlr_buffer.h b/include/wlr/types/wlr_buffer.h
index 28567f26..c57d79ed 100644
--- a/include/wlr/types/wlr_buffer.h
+++ b/include/wlr/types/wlr_buffer.h
@@ -4,9 +4,12 @@
 #include <pixman.h>
 #include <wayland-server.h>
 
+/**
+ * A client buffer.
+ */
 struct wlr_buffer {
-	struct wl_resource *resource;
-	struct wlr_texture *texture;
+	struct wl_resource *resource; // can be NULL
+	struct wlr_texture *texture; // can be NULL
 	bool released;
 	size_t n_refs;
 
@@ -15,21 +18,38 @@ struct wlr_buffer {
 
 struct wlr_renderer;
 
-// Checks if a resource is a wl_buffer.
+/**
+ * Check if a resource is a wl_buffer resource.
+ */
 bool wlr_resource_is_buffer(struct wl_resource *resource);
-// Returns the buffer size.
+/**
+ * Get the size of a wl_buffer resource.
+ */
 bool wlr_buffer_get_resource_size(struct wl_resource *resource,
 	struct wlr_renderer *renderer, int *width, int *height);
 
-// Uploads the texture to the GPU and references it.
+/**
+ * Upload a buffer to the GPU and reference it.
+ */
 struct wlr_buffer *wlr_buffer_create(struct wlr_renderer *renderer,
 	struct wl_resource *resource);
-// References and unreferences the buffer.
+/**
+ * Reference the buffer.
+ */
 void wlr_buffer_ref(struct wlr_buffer *buffer);
+/**
+ * Unreference the buffer. After this call, `buffer` may not be accessed
+ * anymore.
+ */
 void wlr_buffer_unref(struct wlr_buffer *buffer);
-// Tries to update the texture in the provided buffer. This destroys `buffer`
-// and returns a new buffer.
-// Fails if `buffer->n_refs` > 1 or if the texture isn't mutable.
+/**
+ * Try to update the buffer's content. On success, returns the updated buffer
+ * and destroys the provided `buffer`. On error, `buffer` is intact and NULL is
+ * returned.
+ *
+ * Fails if there's more than one reference to the buffer or if the texture
+ * isn't mutable.
+ */
 struct wlr_buffer *wlr_buffer_apply_damage(struct wlr_buffer *buffer,
 	struct wl_resource *resource, pixman_region32_t *damage);