[mutter/wip/nielsdg/add-wayland-buf-docs: 1/3] wayland: Add documentation for dma-buf namespace

[Niels De Graef <nielsdg src gnome org>]

commit 84415f936c2ea9d237ac66b4d3e4e1b3ce1ac3f0
Author: Niels De Graef <niels degraef barco com>
Date:   Mon Oct 21 11:19:21 2019 +0200

    wayland: Add documentation for dma-buf namespace
    
    It's not always clear how the dma-buf functions work (e.g. where memory
    is allocated) without actually going in-depth in the code. This just
    adds a few commments to more quickly gain understanding.
    
    https://gitlab.gnome.org/GNOME/mutter/merge_requests/871

 src/wayland/meta-wayland-dma-buf.c | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
---
diff --git a/src/wayland/meta-wayland-dma-buf.c b/src/wayland/meta-wayland-dma-buf.c
index 914e03a2f..be05a83e9 100644
--- a/src/wayland/meta-wayland-dma-buf.c
+++ b/src/wayland/meta-wayland-dma-buf.c
@@ -25,6 +25,16 @@
  *     Daniel Stone <daniels collabora com>
  */
 
+/**
+ * SECTION:meta-wayland-dma-buf
+ * @title: MetaWaylandDmaBuf
+ * @short_description: Handles passing dma_bufs in Wayland
+ *
+ * The MetaWaylandDmaBuf namespace contains several objects and functions to
+ * handle dma_buf buffers that are passed through from clients in Wayland (e.g.
+ * using the linux_dmabuf_unstable_v1 protocol).
+ */
+
 #include "config.h"
 
 #include "wayland/meta-wayland-dma-buf.h"
@@ -260,6 +270,17 @@ static const struct wl_buffer_interface dma_buf_buffer_impl =
   buffer_destroy,
 };
 
+/**
+ * meta_wayland_dma_buf_from_buffer:
+ * @buffer: A #MetaWaylandBuffer object
+ *
+ * Fetches the associated #MetaWaylandDmaBufBuffer from the wayland buffer.
+ * This does not *create* a new object, as this happens in the create_params
+ * request of linux_dmabuf_unstable_v1.
+ *
+ * Returns: (transfer none): The corresponding #MetaWaylandDmaBufBuffer (or
+ * %NULL if it wasn't a dma_buf-based wayland buffer)
+ */
 MetaWaylandDmaBufBuffer *
 meta_wayland_dma_buf_from_buffer (MetaWaylandBuffer *buffer)
 {
@@ -513,6 +534,18 @@ dma_buf_bind (struct wl_client *client,
   send_modifiers (resource, DRM_FORMAT_RGB565);
 }
 
+/**
+ * meta_wayland_dma_buf_init:
+ * @compositor: The #MetaWaylandCompositor
+ *
+ * Creates the global Wayland object that exposes the linux_dmabuf_unstable_v1
+ * protocol. When a client binds to the resource, Mutter will make sure to
+ * also send the supported DRM format modifiers.
+ *
+ * Returns: Whether the initialization was succesfull. If this is %FALSE,
+ * clients won't be able to use the linux_dmabuf_unstable_v1 protocol to pass
+ * buffers.
+ */
 gboolean
 meta_wayland_dma_buf_init (MetaWaylandCompositor *compositor)
 {