Add documentation for all missing functions

3 files changed, 79 insertions, 1 deletions

diff --git a/gst-libs/gst/cairo/gstcairobuffer.c b/gst-libs/gst/cairo/gstcairobuffer.c
index 7a70af8..3f12311 100644
--- a/gst-libs/gst/cairo/gstcairobuffer.c
+++ b/gst-libs/gst/cairo/gstcairobuffer.c
@@ -118,7 +118,7 @@ gst_cairo_buffer_get_surface (GstCairoBuffer * cbuffer,
 /**
  * gst_cairo_create_surface:
  * @buffer: buffer to create surface from
- * @format: format the buffer is in.
+ * @format: format of the @buffer
  *
  * Creates a cairo surface from the given @buffer. The @buffer must conform 
  * to @format. You may only modify the surface and use it with 
@@ -134,6 +134,22 @@ gst_cairo_create_surface (GstBuffer * buffer, const GstCairoFormat * format)
   return gst_cairo_create_similar_surface (buffer, NULL, format);
 }
 
+/**
+ * gst_cairo_create_similar_surface:
+ * @buffer: buffer to create surface from
+ * @surface: surface the returned surface should be similar to or %NULL if
+ *           no similarities are desired
+ * @format: format of the @buffer
+ *
+ * Creates a cairo surface from the given @buffer that is as similar as
+ * possible to the given @surface. The @buffer must conform to @format.
+ * You may only modify the surface and use it with cairo_create() if the 
+ * @buffer is writable. Using it as a source for drawing operations is fine
+ * in all cases.
+ *
+ * Returns: A new surface referencing the contents of buffer.
+ *          Use cairo_surface_destroy() after use.
+ **/
 cairo_surface_t *
 gst_cairo_create_similar_surface (GstBuffer * buffer,
     cairo_surface_t * surface, const GstCairoFormat * format)
diff --git a/gst-libs/gst/cairo/gstcairoformat.c b/gst-libs/gst/cairo/gstcairoformat.c
index ab11c53..1803ac0 100644
--- a/gst-libs/gst/cairo/gstcairoformat.c
+++ b/gst-libs/gst/cairo/gstcairoformat.c
@@ -209,6 +209,14 @@ gst_cairo_format_to_caps (const GstCairoFormat * format,
   return caps;
 }
 
+/**
+ * gst_cairo_format_get_width:
+ * @format: a format
+ *
+ * Queries the width of a given format
+ *
+ * Returns: the width in pixels
+ **/
 guint
 gst_cairo_format_get_width (const GstCairoFormat * format)
 {
@@ -217,6 +225,14 @@ gst_cairo_format_get_width (const GstCairoFormat * format)
   return format->width;
 }
 
+/**
+ * gst_cairo_format_get_height:
+ * @format: a format
+ *
+ * Queries the height of a given format.
+ *
+ * Returns: the height in pixels
+ **/
 guint
 gst_cairo_format_get_height (const GstCairoFormat * format)
 {
@@ -225,6 +241,15 @@ gst_cairo_format_get_height (const GstCairoFormat * format)
   return format->height;
 }
 
+/**
+ * gst_cairo_format_get_framerate:
+ * @format: a format
+ * @numerator: value to store the framerate's numerator
+ * @denominator: value to store the framerate's denominator
+ *
+ * Queries the framerate of the given @format and stores it in the given 
+ * values.
+ **/
 void
 gst_cairo_format_get_framerate (const GstCairoFormat * format,
     guint * numerator, guint * denominator)
diff --git a/gst-libs/gst/cairo/gstcairopad.c b/gst-libs/gst/cairo/gstcairopad.c
index b285a78..96e74c8 100644
--- a/gst-libs/gst/cairo/gstcairopad.c
+++ b/gst-libs/gst/cairo/gstcairopad.c
@@ -27,6 +27,22 @@
 #include "gstcairoformat-private.h"
 
 /**
+ * gst_cairo_pad_template_new:
+ * @name: name of the template
+ * @dir: direction of template
+ * @presence: presence of pads created from this template
+ *
+ * This is a convenience macro for creating pad templates for use in 
+ * elements that use gst-plugins-cairo. It is recommended to use this
+ * function when creating pad templates in your elements and not use
+ * GstStaticPadTemplate<!-- -->s, because then the element will 
+ * automatically benefit from new formats added to gst-plugins-cairo.
+ *
+ * Returns: a new pad template accepting all formats that 
+ *          gst-plugins-cairo supports.
+ **/
+
+/**
  * gst_cairo_pad_alloc_buffer:
  * @pad: a source pad
  * @buffer: pointer to set the allocated buffer on
@@ -44,6 +60,27 @@ gst_cairo_pad_alloc_buffer (GstPad * pad, GstBuffer ** buffer)
   return gst_cairo_pad_alloc_buffer_full (pad, NULL, NULL, TRUE, buffer);
 }
 
+/**
+ * gst_cairo_pad_alloc_buffer_full:
+ * @pad: a source pad
+ * @restrict_func: function that restricts allowed caps.
+ * @restrict_data: data to pass to @restrict_func
+ * @set_caps: %TRUE to set caps on @pad if the pad doesn't have caps yet.
+ * @buffer: location to store newly allocated buffer
+ *
+ * This is the function you should use to allocate buffers in your element.
+ * Always use this function instead of gst_pad_alloc_buffer() as this 
+ * function will use special features of cairo bufers that allow allocating
+ * accelerated buffers even when different caps are in use by the pad(s).
+ * See gst_cairo_buffer_is_fixed() for a discussion of this feature.
+ * The function will use the caps of @pad to allocate the new buffer.
+ *
+ * Returns: a result code indicating success of the operation. Any result
+ *          code other than GST_FLOW_OK is an error and buf should not be
+ *          used. An error can occur if the pad is not connected or when the
+ *          downstream peer elements cannot provide an acceptable buffer.
+ *          MT safe.
+ **/
 GstFlowReturn
 gst_cairo_pad_alloc_buffer_full (GstPad * pad,
     GstCairoRestrictCapsFunction restrict_func, gpointer restrict_data,