docs: Add missing docblocks for surface observer API

2 files changed, 130 insertions, 5 deletions

diff --git a/src/cairo-surface-observer.c b/src/cairo-surface-observer.c
index 772e18c96..1031b2da3 100644
--- a/src/cairo-surface-observer.c
+++ b/src/cairo-surface-observer.c
@@ -60,7 +60,16 @@
  * @Short_Description: Observing other surfaces
  * @See_Also: #cairo_surface_t
  *
- * A surface that exists solely to watch another is doing.
+ * A surface that exists solely to watch what another surface is doing.
+ */
+
+/**
+ * CAIRO_HAS_OBSERVER_SURFACE:
+ *
+ * Defined if the observer surface backend is available.
+ * This macro can be used to conditionally compile backend-specific code.
+ *
+ * Since: 1.12
  */
 
 static const cairo_surface_backend_t _cairo_surface_observer_backend;
@@ -1382,8 +1391,8 @@ static const cairo_surface_backend_t _cairo_surface_observer_backend = {
  * the process it will log operations and times, which are fast, which are
  * slow, which are frequent, etc.
  *
- * The @mode parameter can be set to either CAIRO_SURFACE_OBSERVER_NORMAL
- * or CAIRO_SURFACE_OBSERVER_RECORD_OPERATIONS, to control whether or not
+ * The @mode parameter can be set to either %CAIRO_SURFACE_OBSERVER_NORMAL
+ * or %CAIRO_SURFACE_OBSERVER_RECORD_OPERATIONS, to control whether or not
  * the internal observer should record operations.
  *
  * Return value: a pointer to the newly allocated surface. The caller
@@ -1438,6 +1447,18 @@ _cairo_surface_observer_add_callback (cairo_list_t *head,
     return CAIRO_STATUS_SUCCESS;
 }
 
+/**
+ * cairo_surface_observer_add_paint_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback function for paint operations
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for paint operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.12
+ */
 cairo_status_t
 cairo_surface_observer_add_paint_callback (cairo_surface_t *abstract_surface,
 					    cairo_surface_observer_callback_t func,
@@ -1456,6 +1477,18 @@ cairo_surface_observer_add_paint_callback (cairo_surface_t *abstract_surface,
 						 func, data);
 }
 
+/**
+ * cairo_surface_observer_add_mask_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback function for mask operations
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for mask operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.12
+ */
 cairo_status_t
 cairo_surface_observer_add_mask_callback (cairo_surface_t *abstract_surface,
 					  cairo_surface_observer_callback_t func,
@@ -1474,6 +1507,18 @@ cairo_surface_observer_add_mask_callback (cairo_surface_t *abstract_surface,
 						 func, data);
 }
 
+/**
+ * cairo_surface_observer_add_fill_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback function for fill operations
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for fill operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.12
+ */
 cairo_status_t
 cairo_surface_observer_add_fill_callback (cairo_surface_t *abstract_surface,
 					  cairo_surface_observer_callback_t func,
@@ -1492,6 +1537,18 @@ cairo_surface_observer_add_fill_callback (cairo_surface_t *abstract_surface,
 						 func, data);
 }
 
+/**
+ * cairo_surface_observer_add_stroke_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback function for stroke operations
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for stroke operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.12
+ */
 cairo_status_t
 cairo_surface_observer_add_stroke_callback (cairo_surface_t *abstract_surface,
 					    cairo_surface_observer_callback_t func,
@@ -1510,6 +1567,18 @@ cairo_surface_observer_add_stroke_callback (cairo_surface_t *abstract_surface,
 						 func, data);
 }
 
+/**
+ * cairo_surface_observer_add_glyphs_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback function for glyph operations
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for glyph operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.10
+ */
 cairo_status_t
 cairo_surface_observer_add_glyphs_callback (cairo_surface_t *abstract_surface,
 					    cairo_surface_observer_callback_t func,
@@ -1528,6 +1597,18 @@ cairo_surface_observer_add_glyphs_callback (cairo_surface_t *abstract_surface,
 						 func, data);
 }
 
+/**
+ * cairo_surface_observer_add_flush_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback for flush operations
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for flush operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.10
+ */
 cairo_status_t
 cairo_surface_observer_add_flush_callback (cairo_surface_t *abstract_surface,
 					   cairo_surface_observer_callback_t func,
@@ -1546,6 +1627,18 @@ cairo_surface_observer_add_flush_callback (cairo_surface_t *abstract_surface,
 						 func, data);
 }
 
+/**
+ * cairo_surface_observer_add_finish_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback function for the finish operation
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for finish operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.10
+ */
 cairo_status_t
 cairo_surface_observer_add_finish_callback (cairo_surface_t *abstract_surface,
 					    cairo_surface_observer_callback_t func,
@@ -1966,6 +2059,18 @@ _cairo_observation_print (cairo_output_stream_t *stream,
     cairo_device_destroy (script);
 }
 
+/**
+ * cairo_surface_observer_print:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @write_func: callback for writing on a stream
+ * @closure: data to pass to @write_func
+ *
+ * Prints the observer log using the given callback.
+ *
+ * Returns: the status of the print operation
+ *
+ * Since: 1.12
+ */
 cairo_status_t
 cairo_surface_observer_print (cairo_surface_t *abstract_surface,
 			      cairo_write_func_t write_func,
@@ -1987,6 +2092,16 @@ cairo_surface_observer_print (cairo_surface_t *abstract_surface,
     return _cairo_output_stream_destroy (stream);
 }
 
+/**
+ * cairo_surface_observer_elapsed:
+ * @abstract_surface: a #cairo_surface_observer_t
+ *
+ * Returns the total observation time.
+ *
+ * Returns: the elapsed time, in nanoseconds
+ *
+ * Since: 1.12
+ */
 double
 cairo_surface_observer_elapsed (cairo_surface_t *abstract_surface)
 {
diff --git a/src/cairo.h b/src/cairo.h
index e026a5283..89e4a070e 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -2400,6 +2400,16 @@ cairo_public cairo_surface_t *
 cairo_surface_create_observer (cairo_surface_t *target,
 			       cairo_surface_observer_mode_t mode);
 
+/**
+ * cairo_surface_observer_callback_t:
+ * @observer: the #cairo_surface_observer_t
+ * @target: the observed surface
+ * @data: closure used when adding the callback
+ *
+ * A generic callback function for surface operations.
+ *
+ * Since: 1.12
+ **/
 typedef void (*cairo_surface_observer_callback_t) (cairo_surface_t *observer,
 						   cairo_surface_t *target,
 						   void *data);
@@ -2440,11 +2450,11 @@ cairo_surface_observer_add_finish_callback (cairo_surface_t *abstract_surface,
 					    void *data);
 
 cairo_public cairo_status_t
-cairo_surface_observer_print (cairo_surface_t *surface,
+cairo_surface_observer_print (cairo_surface_t *abstract_surface,
 			      cairo_write_func_t write_func,
 			      void *closure);
 cairo_public double
-cairo_surface_observer_elapsed (cairo_surface_t *surface);
+cairo_surface_observer_elapsed (cairo_surface_t *abstract_surface);
 
 cairo_public cairo_status_t
 cairo_device_observer_print (cairo_device_t *abstract_device,