docs: Add missing docblocks for cairo-tee API

The tee API has been left undocumented all this time.

2 files changed, 55 insertions, 5 deletions

diff --git a/src/cairo-tee-surface.c b/src/cairo-tee-surface.c
index 47f1175d5..35baa9609 100644
--- a/src/cairo-tee-surface.c
+++ b/src/cairo-tee-surface.c
@@ -42,7 +42,7 @@
  * @See_Also: #cairo_surface_t
  *
  * The "tee" surface supports redirecting all its input to multiple surfaces.
- */
+ **/
 
 /**
  * CAIRO_HAS_TEE_SURFACE:
@@ -434,6 +434,22 @@ static const cairo_surface_backend_t cairo_tee_surface_backend = {
     _cairo_tee_surface_show_text_glyphs
 };
 
+/**
+ * cairo_tee_surface_create:
+ * @primary: the primary #cairo_surface_t
+ *
+ * Creates a new "tee" surface.
+ *
+ * The @primary surface is used when querying surface options, like
+ * font options and extents.
+ *
+ * Operations performed on the tee surface will be replayed on any
+ * surface added to it.
+ *
+ * Returns: the newly created surface
+ *
+ * Since: 1.10
+ **/
 cairo_surface_t *
 cairo_tee_surface_create (cairo_surface_t *primary)
 {
@@ -459,6 +475,16 @@ cairo_tee_surface_create (cairo_surface_t *primary)
     return &surface->base;
 }
 
+/**
+ * cairo_tee_surface_add:
+ * @abstract_surface: a #cairo_tee_surface_t
+ * @target: the surface to add
+ *
+ * Adds a new target surface to the list of replicas of a
+ * tee surface.
+ *
+ * Since: 1.10
+ **/
 void
 cairo_tee_surface_add (cairo_surface_t *abstract_surface,
 		       cairo_surface_t *target)
@@ -496,6 +522,16 @@ cairo_tee_surface_add (cairo_surface_t *abstract_surface,
     }
 }
 
+/**
+ * cairo_tee_surface_remove:
+ * @abstract_surface: a #cairo_tee_surface_t
+ * @target: the surface to remove
+ *
+ * Removes the given surface from the list of replicas of a
+ * tee surface.
+ *
+ * Since: 1.10
+ **/
 void
 cairo_tee_surface_remove (cairo_surface_t *abstract_surface,
 			  cairo_surface_t *target)
@@ -544,6 +580,20 @@ cairo_tee_surface_remove (cairo_surface_t *abstract_surface,
     surface->replicas.num_elements--; /* XXX: cairo_array_remove()? */
 }
 
+/**
+ * cairo_tee_surface_index:
+ * @abstract_surface: a #cairo_tee_surface_t
+ * @index: the index of the replica to retrieve
+ *
+ * Retrieves the replica surface at the given index.
+ *
+ * The primary surface used to create the #cairo_tee_surface_t is
+ * always set at the zero index.
+ *
+ * Returns: the surface at the given index
+ *
+ * Since: 1.10
+ **/
 cairo_surface_t *
 cairo_tee_surface_index (cairo_surface_t *abstract_surface,
 			 unsigned int index)
diff --git a/src/cairo-tee.h b/src/cairo-tee.h
index 9125a3a4a..58264ffff 100644
--- a/src/cairo-tee.h
+++ b/src/cairo-tee.h
@@ -43,18 +43,18 @@
 CAIRO_BEGIN_DECLS
 
 cairo_public cairo_surface_t *
-cairo_tee_surface_create (cairo_surface_t *master);
+cairo_tee_surface_create (cairo_surface_t *primary);
 
 cairo_public void
-cairo_tee_surface_add (cairo_surface_t *surface,
+cairo_tee_surface_add (cairo_surface_t *abstract_surface,
 		       cairo_surface_t *target);
 
 cairo_public void
-cairo_tee_surface_remove (cairo_surface_t *surface,
+cairo_tee_surface_remove (cairo_surface_t *abstract_surface,
 			  cairo_surface_t *target);
 
 cairo_public cairo_surface_t *
-cairo_tee_surface_index (cairo_surface_t *surface,
+cairo_tee_surface_index (cairo_surface_t *abstract_surface,
 			 unsigned int index);
 
 CAIRO_END_DECLS