[clutter/wip/actor-content: 10/24] docs: Add Image and ImageLoader documentation

[Emmanuele Bassi <ebassi src gnome org>]

commit 8903371fda191a1da72a0068924ce00144408f44
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Fri Dec 10 16:04:28 2010 +0000

    docs: Add Image and ImageLoader documentation

 clutter/clutter-image-loader.c |   85 ++++++++++++++++++++++++++++++++++++++++
 clutter/clutter-image-loader.h |   26 ++++++++++++
 clutter/clutter-image.c        |    2 +-
 clutter/clutter-image.h        |    7 +++
 4 files changed, 119 insertions(+), 1 deletions(-)
---
diff --git a/clutter/clutter-image-loader.c b/clutter/clutter-image-loader.c
index 544cd29..e597694 100644
--- a/clutter/clutter-image-loader.c
+++ b/clutter/clutter-image-loader.c
@@ -22,6 +22,18 @@
  *   Emmanuele Bassi <ebassi linux intel com>
  */
 
+/**
+ * SECTION:clutter-image-loader
+ * @Title: ClutterImageLoader
+ * @Short_Description: Image loading abstraction
+ *
+ * #ClutterImageLoader is a class implemented through GIO extension
+ * points. It is an opaque class that delegates the logic for loading
+ * image data synchronously and asynchronously to #ClutterImage.
+ *
+ * #ClutterImageLoader is available since Clutter 1.6
+ */
+
 #include "config.h"
 
 #include "clutter-image-loader.h"
@@ -83,6 +95,16 @@ get_default_image_loader (gpointer data)
     return (gpointer) G_TYPE_INVALID;
 }
 
+/*< private >
+ * clutter_image_loader_new:
+ *
+ * Creates a new #ClutterImageLoader instance, proxying the
+ * real instance created through GIO extension points.
+ *
+ * Return value: the newly created #ClutterImageLoader proxy
+ *
+ * Since: 1.6
+ */
 ClutterImageLoader *
 _clutter_image_loader_new (void)
 {
@@ -108,6 +130,16 @@ _clutter_image_loader_new (void)
   return loader;
 }
 
+/*< private >
+ * clutter_image_loader_get_image_size:
+ * @loader: a #ClutterImageLoader
+ * @width: (out): return location for the image width, or %NULL
+ * @height: (out): return location for the image height, or %NULL
+ *
+ * Queries the size of the loaded image.
+ *
+ * Since: 1.6
+ */
 void
 _clutter_image_loader_get_image_size (ClutterImageLoader *loader,
                                       gint               *width,
@@ -120,6 +152,17 @@ _clutter_image_loader_get_image_size (ClutterImageLoader *loader,
                                                            height);
 }
 
+/*< private >
+ * clutter_image_loader_get_texture_handle:
+ * @loader: a #ClutterImageLoader
+ *
+ * Retrieves the Cogl handle for the texture containing the loaded image.
+ *
+ * Return value: (transfer none): a pointer to the texture handle.
+ *   The #ClutterImageLoader owns the returned handle
+ *
+ * Since: 1.6
+ */
 CoglHandle
 _clutter_image_loader_get_texture_handle (ClutterImageLoader *loader)
 {
@@ -128,6 +171,19 @@ _clutter_image_loader_get_texture_handle (ClutterImageLoader *loader)
   return CLUTTER_IMAGE_LOADER_GET_CLASS (loader)->get_texture_handle (loader);
 }
 
+/*< private >
+ * clutter_image_loader_load_stream:
+ * @loader: a #ClutterImageLoader
+ * @stream: a #GInputStream
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for a #GError or %NULL
+ *
+ * Synchronously loads image data from an input @stream.
+ *
+ * Return value: %TRUE if the image data was successfully loaded
+ *
+ * Since: 1.6
+ */
 gboolean
 _clutter_image_loader_load_stream (ClutterImageLoader  *loader,
                                    GInputStream        *stream,
@@ -145,6 +201,20 @@ _clutter_image_loader_load_stream (ClutterImageLoader  *loader,
                                                                error);
 }
 
+/*< private >
+ * clutter_image_loader_load_stream_async:
+ * @loader: a #ClutterImageLoader
+ * @stream: a #GInputStream
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @callback: (scope async): a callback
+ * @user_data: closure for @callback
+ *
+ * Starts an asynchronous load of image data from an input @stream.
+ *
+ * When done, @callback will be invoked.
+ *
+ * Since: 1.6
+ */
 void
 _clutter_image_loader_load_stream_async (ClutterImageLoader  *loader,
                                          GInputStream        *stream,
@@ -163,6 +233,21 @@ _clutter_image_loader_load_stream_async (ClutterImageLoader  *loader,
                                                               user_data);
 }
 
+/*< private >
+ * clutter_image_loader_load_stream_finish:
+ * @loader: a #ClutterImageLoader
+ * @result: a #GAsyncResult
+ * @error: return location for a #GError or %NULL
+ *
+ * Finishes the asynchronous loading started by
+ * clutter_image_loader_load_stream_async(). This function must be
+ * called in the callback function.
+ *
+ * Return value: %TRUE if the image loading was successful
+ *   and %FALSE otherwise
+ *
+ * Since: 1.6
+ */
 gboolean
 _clutter_image_loader_load_stream_finish (ClutterImageLoader  *loader,
                                           GAsyncResult        *result,
diff --git a/clutter/clutter-image-loader.h b/clutter/clutter-image-loader.h
index 687c157..49dc142 100644
--- a/clutter/clutter-image-loader.h
+++ b/clutter/clutter-image-loader.h
@@ -42,18 +42,44 @@ G_BEGIN_DECLS
 #define CLUTTER_IS_IMAGE_LOADER_CLASS(klass)    (G_TYPE_CHECK_CLASS_TYPE ((klass), CLUTTER_TYPE_IMAGE_LOADER))
 #define CLUTTER_IMAGE_LOADER_GET_CLASS(obj)     (G_TYPE_INSTANCE_GET_CLASS ((obj), CLUTTER_TYPE_IMAGE_LOADER, ClutterImageLoaderClass))
 
+/**
+ * CLUTTER_IMAGE_LOADER_EXTENSION_POINT_NAME:
+ *
+ * Evaluates to the extension point name that can be used by modules
+ * to provide the implementation of image loading logic.
+ *
+ * Since: 1.6
+ */
 #define CLUTTER_IMAGE_LOADER_EXTENSION_POINT_NAME       "clutter-image-loader"
 
 typedef struct _ClutterImageLoader              ClutterImageLoader;
 typedef struct _ClutterImageLoaderClass         ClutterImageLoaderClass;
 
+/**
+ * ClutterImageLoader:
+ *
+ * The <structname>ClutterImageLoader</structname> structure contains
+ * only private data and should be accessed using the provided API.
+ *
+ * Since: 1.6
+ */
 struct _ClutterImageLoader
 {
+  /*< private >*/
   GObject parent_instance;
 };
 
+/**
+ * ClutterImageLoaderClass:
+ *
+ * The <structname>ClutterImageLoaderClass</structname> structure
+ * contains only private data.
+ *
+ * Since: 1.6
+ */
 struct _ClutterImageLoaderClass
 {
+  /*< private >*/
   GObjectClass parent_class;
 
   gboolean (* is_supported) (void);
diff --git a/clutter/clutter-image.c b/clutter/clutter-image.c
index 04e759e..6e6bfbc 100644
--- a/clutter/clutter-image.c
+++ b/clutter/clutter-image.c
@@ -260,7 +260,7 @@ clutter_image_init (ClutterImage *image)
  * Image data should be loaded using one of the clutter_image_load* family
  * of functions.
  *
- * Return value: the newly created #ClutterImage instance
+ * Return value: (transfer full): the newly created #ClutterImage instance
  *
  * Since: 1.6
  */
diff --git a/clutter/clutter-image.h b/clutter/clutter-image.h
index d5b30c8..53ecf79 100644
--- a/clutter/clutter-image.h
+++ b/clutter/clutter-image.h
@@ -42,6 +42,13 @@ G_BEGIN_DECLS
 #define CLUTTER_IS_IMAGE_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), CLUTTER_TYPE_IMAGE))
 #define CLUTTER_IMAGE_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), CLUTTER_TYPE_IMAGE, ClutterImageClass))
 
+/**
+ * CLUTTER_IMAGE_ERROR:
+ *
+ * Error domain for #ClutterImage errors.
+ *
+ * Since: 1.6
+ */
 #define CLUTTER_IMAGE_ERROR             (clutter_image_error_quark ())
 
 typedef struct _ClutterImage            ClutterImage;