[glide] Documenting GlideSlide

[Robert Carr <racarr src gnome org>]

commit 21bad7c0f4c3f4ce2c10e32122d0f75a87c39f7b
Author: Robert Carr <racarr Valentine localdomain>
Date:   Fri May 7 13:21:21 2010 -0400

    Documenting GlideSlide

 docs/reference/glide-sections.txt |   10 +--
 libglide/glide-image.c            |   47 +++++++++++++++
 libglide/glide-slide.c            |  119 +++++++++++++++++++++++++++++++++++--
 3 files changed, 165 insertions(+), 11 deletions(-)
---
diff --git a/docs/reference/glide-sections.txt b/docs/reference/glide-sections.txt
index f3d579c..63a336a 100644
--- a/docs/reference/glide-sections.txt
+++ b/docs/reference/glide-sections.txt
@@ -10,21 +10,20 @@ glide_init
 <FILE>glide-slide</FILE>
 <TITLE>GlideSlide</TITLE>
 GlideSlideClass
-GlideSlidePrivate
 GlideSlide
 glide_slide_new
 glide_slide_construct_from_json
+glide_slide_add_actor_content
+glide_slide_get_contents
 glide_slide_set_background
 glide_slide_get_background
 glide_slide_set_animation
 glide_slide_get_animation
-glide_slide_add_actor_content
-glide_slide_get_contents
+glide_slide_get_index
+glide_slide_set_index
 glide_slide_set_color
 glide_slide_get_color
 glide_slide_resize
-glide_slide_get_index
-glide_slide_set_index
 <SUBSECTION Standard>
 GLIDE_SLIDE
 GLIDE_IS_SLIDE
@@ -425,7 +424,6 @@ GLIDE_TEXT_GET_CLASS
 <TITLE>GlideImage</TITLE>
 GlideImage
 GlideImageClass
-GlideImagePrivate
 glide_image_new
 glide_image_new_from_file
 glide_image_set_from_file
diff --git a/libglide/glide-image.c b/libglide/glide-image.c
index d4e4795..75b5ff8 100644
--- a/libglide/glide-image.c
+++ b/libglide/glide-image.c
@@ -333,6 +333,13 @@ glide_image_init (GlideImage *self)
 				   COGL_MATERIAL_FILTER_LINEAR);
 }
 
+/**
+ * glide_image_new:
+ *
+ * Returns a new #GlideImage.
+ *
+ * Return value: The newly allocated #GlideImage actor.
+ */
 ClutterActor*
 glide_image_new ()
 {
@@ -340,6 +347,14 @@ glide_image_new ()
 		       NULL);
 }
 
+/**
+ * glide_image_set_cogl_texture:
+ * @image: A #GlideImage.
+ * @new_texture: A @CoglHandle corresponding to the new texture.
+ *
+ * Sets @image to display @new_texture.
+ *
+ */
 void
 glide_image_set_cogl_texture (GlideImage *image,
 			      CoglHandle new_texture)
@@ -361,6 +376,17 @@ glide_image_set_cogl_texture (GlideImage *image,
   cogl_handle_unref (new_texture);
 }
 
+/**
+ * glide_image_set_from_file:
+ * @image: A #GlideImage
+ * @filename: The image file to load.
+ * @error: Location to store error.
+ *
+ * Sets @image to display the image at @filename. This will cause
+ * @filename to be imported as a resource if it is not already present.
+ *
+ * Return value: %TRUE on success, %FALSE on failure.
+ */
 gboolean
 glide_image_set_from_file (GlideImage *image,
 			   const gchar *filename,
@@ -406,6 +432,16 @@ glide_image_set_from_file (GlideImage *image,
   return TRUE;
 }
 
+/**
+ * glide_image_new_from_file:
+ * @filename: An image file path.
+ * @error: Location to store error.
+ *
+ * Constructs a new #GlideImage and sets it to
+ * display the image at @filename.
+ *
+ * Return value: The newly allocated #GlideImage.
+ */
 ClutterActor *
 glide_image_new_from_file (const gchar *filename, 
 			   GError **error)
@@ -427,6 +463,17 @@ glide_image_new_from_file (const gchar *filename,
     }
 }
 
+/**
+ * glide_image_get_filename:
+ * @image: A #GlideImage
+ *
+ * Returns the current file name for the image. 
+ *
+ * BUG: Textures...gradients and stuff in future...resources?
+ * behavior of this is a little ill defined.
+ *
+ * Return value: A path to the file in use by @image.
+ */
 const gchar *
 glide_image_get_filename (GlideImage *image)
 {
diff --git a/libglide/glide-slide.c b/libglide/glide-slide.c
index eef9aef..69beb93 100644
--- a/libglide/glide-slide.c
+++ b/libglide/glide-slide.c
@@ -658,20 +658,45 @@ glide_slide_init (GlideSlide *self)
   CLUTTER_ACTOR_SET_FLAGS (self, CLUTTER_ACTOR_NO_LAYOUT);
 }
 
+/**
+ * glide_slide_add_actor_content:
+ * @slide: A #GlideSlide
+ * @actor: A #ClutterActor to add to the contents group of @slide.
+ *
+ * Adds @actor to the contents group of @slide.
+ *
+ */
 void
-glide_slide_add_actor_content (GlideSlide *s, ClutterActor *a)
+glide_slide_add_actor_content (GlideSlide *slide, ClutterActor *actor)
 {
-  clutter_container_add_actor (CLUTTER_CONTAINER (s->priv->contents_group), a);
+  clutter_container_add_actor (CLUTTER_CONTAINER (slide->priv->contents_group), actor);
 }
 
+/**
+ * glide_slide_new:
+ * @document: The #GlideDocument to which the new slide belongs.
+ *
+ * Constructs a new slide, belonging to @document.
+ *
+ * Return value: The newly allocated #GlideSlide
+ */
 GlideSlide*
-glide_slide_new (GlideDocument *d)
+glide_slide_new (GlideDocument *document)
 {
   return g_object_new (GLIDE_TYPE_SLIDE, 
-		       "document", d,
+		       "document", document,
 		       NULL);
 }
 
+/**
+ * glide_slide_construct_from_json:
+ * @slide: A #GlideSlide
+ * @slide_obj: A #JsonObject containing serialized slide data.
+ * @manager: The #GlideStageManager responsible for the slide.
+ *
+ * BUG: Essentially the deserialize implementation for GlideSlide...
+ * however due to some old API flaws, it's like this now. FIXME?
+ */
 void
 glide_slide_construct_from_json (GlideSlide *slide, JsonObject *slide_obj, GlideStageManager *manager)
 {
@@ -734,6 +759,15 @@ glide_slide_material_for_file (const gchar *filename)
   return m;
 }
 
+/**
+ * glide_slide_set_background:
+ * @slide: A #GlideSlide
+ * @background: A path to be used for the new background image.
+ *
+ * Sets the background image of @slide to be the image located at
+ * the path @background. This causes an import of @background
+ * as a document resource, if it does not already exist
+ */
 void 
 glide_slide_set_background (GlideSlide *slide, const gchar *background)
 {
@@ -764,12 +798,29 @@ glide_slide_set_background (GlideSlide *slide, const gchar *background)
   clutter_actor_queue_redraw (CLUTTER_ACTOR (slide));
 }
 
+/**
+ * glide_slide_get_background:
+ * @slide: A #GlideSlide
+ *
+ * Returns the resource name of the slides background image.
+ *
+ * Return value: The background image resource name for @slide.
+ */
 const gchar *
 glide_slide_get_background (GlideSlide *slide)
 {
   return slide->priv->background;
 }
 
+/**
+ * glide_slide_set_animation:
+ * @slide: A #GlideSlide
+ * @info: A #GlideAnimationInfo to set as the new animation.
+ *
+ * Sets the animation setting of @slide to the animation described
+ * by @info.
+ *
+ */
 void 
 glide_slide_set_animation (GlideSlide *slide, const GlideAnimationInfo *info)
 {
@@ -780,18 +831,44 @@ glide_slide_set_animation (GlideSlide *slide, const GlideAnimationInfo *info)
   g_object_notify (G_OBJECT (slide), "animation");
 }
 
+/**
+ * glide_slide_get_animation:
+ * @slide: A #GlideSlide
+ *
+ * Returns the current animation for @slide.
+ *
+ * Return value: The current animation setting for @slide.
+ */
 GlideAnimationInfo *
 glide_slide_get_animation (GlideSlide *slide)
 {
   return slide->priv->animation;
 }
 
+/**
+ * glide_slide_get_contents:
+ * @slide: A #GlideSlide
+ *
+ * Returns the internal contents group for the slide,
+ * currently of type #ClutterGroup. This contains
+ * all actors (but not the background).
+ *
+ * Return value: The contents group for @slide.
+ */
 ClutterActor *
 glide_slide_get_contents (GlideSlide *slide)
 {
   return slide->priv->contents_group;
 }
 
+/**
+ * glide_slide_set_color:
+ * @slide: A #GlideSlide
+ * @color: A #ClutterColor to set as the new color
+ *
+ * Sets the background color of @slide to @color.
+ *
+ */
 void 
 glide_slide_set_color (GlideSlide *slide, const ClutterColor *color)
 {
@@ -801,12 +878,29 @@ glide_slide_set_color (GlideSlide *slide, const ClutterColor *color)
   clutter_actor_queue_redraw (CLUTTER_ACTOR (slide));
 }
 
+/**
+ * glide_slide_get_color:
+ * @slide: A #GlideSlide
+ * @color: A location to store the return #ClutterColor
+ *
+ * Returns the current background color of @slide through the @color variable.
+ *
+ */
 void 
 glide_slide_get_color (GlideSlide *slide, ClutterColor *color)
 {
   *color = slide->priv->color;
 }
 
+/**
+ * glide_slide_resize:
+ * @slide: A #GlideSlide
+ * @width: A new width, in pixels.
+ * @height: A new height, in pixels.
+ *
+ * Resizes @slide and it's contents to be displayed at @width by @height size
+ *
+ */
 void
 glide_slide_resize (GlideSlide *slide, gfloat width, gfloat height)
 {
@@ -851,13 +945,28 @@ glide_slide_resize (GlideSlide *slide, gfloat width, gfloat height)
     }
 }
 
-
+/**
+ * glide_slide_get_index:
+ * @slide: A #GlideSlide.
+ *
+ * Return the current index of @slide in it's containing
+ * #GlideDocument.
+ *
+ * Return value: The index of @slide.
+ */
 guint 
 glide_slide_get_index (GlideSlide *slide)
 {
   return slide->priv->index;
 }
 
+/**
+ * glide_slide_set_index:
+ * @slide: A #GlideSlide.
+ * @index: The index to set.
+ *
+ * Sets the index of @slide to @index.
+ */
 void
 glide_slide_set_index (GlideSlide *slide, guint index)
 {