[glide] Some stage manager documentation + API guards

[Robert Carr <racarr src gnome org>]

commit 17f53c5a6f90be4d8142a25f21b7e110a1935d72
Author: Robert Carr <racarr Valentine localdomain>
Date:   Fri May 7 20:20:23 2010 -0400

    Some stage manager documentation + API guards

 libglide/glide-stage-manager.c |  128 ++++++++++++++++++++++++++++++++++++----
 1 files changed, 117 insertions(+), 11 deletions(-)
---
diff --git a/libglide/glide-stage-manager.c b/libglide/glide-stage-manager.c
index 69397c8..3e97ac4 100644
--- a/libglide/glide-stage-manager.c
+++ b/libglide/glide-stage-manager.c
@@ -220,11 +220,24 @@ glide_stage_manager_add_manipulator (GlideStageManager *manager)
   manager->priv->manip = g_object_ref (G_OBJECT (manip));
 }
 
+/**
+ * glide_stage_manager_set_slide:
+ * @manager: A #GlideStageManager
+ * @slide: Index of new current slide for @manager
+ *
+ * Sets the current slide for @manager to the slide at
+ * index @slide in the document.
+ *
+ */
 void 
 glide_stage_manager_set_slide (GlideStageManager *manager,
 			       guint slide)
 {
-  GlideSlide *a, *b = glide_document_get_nth_slide (manager->priv->document, slide);
+  GlideSlide *a, *b;
+  
+  g_return_if_fail (GLIDE_IS_STAGE_MANAGER (manager));
+
+  b = glide_document_get_nth_slide (manager->priv->document, slide);
   
   if (manager->priv->current_slide == slide)
     return;
@@ -290,10 +303,22 @@ glide_stage_manager_document_slide_added_cb (GlideDocument *document,
   glide_stage_manager_set_selection (manager, GLIDE_ACTOR (slide));
 }
 
+/**
+ * glide_stage_manager_set_document:
+ * @manager: A #GlideStageManager
+ * @document: A #GlideDocument
+ *
+ * Sets @document as the document of @manager.
+ *
+ * BUG: Should probably be a construct only property?
+ */
 void
 glide_stage_manager_set_document (GlideStageManager *manager,
 				  GlideDocument *document)
 {
+  g_return_if_fail (GLIDE_IS_STAGE_MANAGER (manager));
+  g_return_if_fail (GLIDE_IS_DOCUMENT (document));
+
   manager->priv->document = g_object_ref (document);
   g_signal_connect (document, "slide-added", G_CALLBACK (glide_stage_manager_document_slide_added_cb), manager);
   g_signal_connect (document, "slide-removed", G_CALLBACK (glide_stage_manager_document_slide_removed_cb), manager);
@@ -308,9 +333,18 @@ glide_stage_manager_timeline_completed (ClutterTimeline *timeline,
   manager->priv->animating = FALSE;
 }
 
+/**
+ * glide_stage_manager_advance_slide:
+ * @manager: A #GlideStageManager 
+ *
+ * Advances to the next slide for @manager with animations.
+ *
+ */
 void
 glide_stage_manager_advance_slide (GlideStageManager *manager)
 {
+  g_return_if_fail (GLIDE_IS_STAGE_MANAGER (manager));
+
   if (manager->priv->animating)
     return;
   if (manager->priv->current_slide + 1 < glide_document_get_n_slides(manager->priv->document))
@@ -344,13 +378,25 @@ glide_stage_manager_advance_slide (GlideStageManager *manager)
     glide_stage_manager_set_presenting (manager, FALSE);
 }
 
+/**
+ * glide_stage_manager_reverse_slide:
+ * @manager: A #GlideStageManager
+ *
+ * Advances to the previous slide for @manager with animations.
+ *
+ * BUG: This is for presenting, but kind of weird with the set_slide_next/prev API.
+ *      actually the whole slide API sucks...have to use document+manager to get a slide?
+ *     
+ */
 void
 glide_stage_manager_reverse_slide (GlideStageManager *manager)
 {
+  g_return_if_fail (GLIDE_IS_STAGE_MANAGER (manager));
+
   glide_stage_manager_set_slide_prev (manager);
 }
 
-gboolean
+static gboolean
 glide_stage_manager_button_pressed (ClutterActor *actor,
 				    ClutterEvent *event,
 				    GlideStageManager *manager)
@@ -829,38 +875,86 @@ glide_stage_manager_init (GlideStageManager *manager)
   manager->priv = GLIDE_STAGE_MANAGER_GET_PRIVATE (manager);
 }
 
+/**
+ * glide_stage_manager_new:
+ * @document: A #GlideDocument
+ * @stage: A #ClutterStage
+ *
+ * Constructs a new stage manager, which manages @document on @stage.
+ * including creating/adding the actors.
+ *
+ * Return value: The new #GlideStageManager
+ */
 GlideStageManager *
 glide_stage_manager_new (GlideDocument *document, ClutterStage *stage)
 {
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), NULL);
+  g_return_val_if_fail (CLUTTER_IS_STAGE (stage), NULL);
   return g_object_new (GLIDE_TYPE_STAGE_MANAGER,
 		       "document", document,
 		       "stage", stage,
 		       NULL);
 }
 
+/**
+ * glide_stage_manager_get_stage:
+ * @manager: A #GlideStageManager
+ *
+ * Returns the #ClutterStage managed by @manager.
+ *
+ * Return value: The #ClutterStage for @manager.
+ */
 ClutterStage *
-glide_stage_manager_get_stage (GlideStageManager *m)
+glide_stage_manager_get_stage (GlideStageManager *manager)
 {
-  return (ClutterStage *)m->priv->stage;
+  g_return_val_if_fail (GLIDE_IS_STAGE_MANAGER (manager), NULL);
+  return (ClutterStage *)manager->priv->stage;
 }
 
+/**
+ * glide_stage_manager_get_selection:
+ * @manager: A #GlideStageManager
+ *
+ * Returns the currently selected actor for @manager.
+ *
+ * Return value: The currently selected actor for @manager.
+ */
 GlideActor *
-glide_stage_manager_get_selection (GlideStageManager *m)
+glide_stage_manager_get_selection (GlideStageManager *manager)
 {
-  return m->priv->selection;
+  g_return_val_if_fail (GLIDE_IS_STAGE_MANAGER (manager), NULL);
+  return manager->priv->selection;
 }
 
+/**
+ * glide_stage_manager_set_selection:
+ * @manager: A #GlideStageManager
+ * @actor: A #GlideActor to set as the new selection, or %NULL.
+ *
+ * Sets @actor as the current selection of @manager.
+ */
 void
-glide_stage_manager_set_selection (GlideStageManager *m,
-				   GlideActor *a)
+glide_stage_manager_set_selection (GlideStageManager *manager,
+				   GlideActor *actor)
 {
-  glide_stage_manager_set_selection_real (m, a);
+  g_return_if_fail (GLIDE_IS_STAGE_MANAGER (manager));
+  glide_stage_manager_set_selection_real (manager, actor);
 }
 
+/**
+ * glide_stage_manager_get_manipulator:
+ * @manager: A #GlideStageManager
+ *
+ * Returns the #GlideManipulator for @manager, used to manipulate
+ * the selected actor.
+ *
+ * Return value: The #GlideManipulator for @manager
+ */
 GlideManipulator *
-glide_stage_manager_get_manipulator (GlideStageManager *m)
+glide_stage_manager_get_manipulator (GlideStageManager *manager)
 {
-  return m->priv->manip;
+  g_return_val_if_fail (GLIDE_IS_STAGE_MANAGER (manager), NULL);
+  return manager->priv->manip;
 }
 
 static void
@@ -878,12 +972,24 @@ glide_stage_manager_get_center_pos (ClutterActor *actor,
   *y = floor(p_height/2.0 - height/2.0);
 }
 
+/**
+ * glide_stage_manager_add_actor:
+ * @manager: A #GlideStageManager
+ * @actor: A new #GlideActor to add
+ *
+ * Adds @actor to the current slide for @manager. 
+ * Primarily used for newly created actors.
+ */
 void 
 glide_stage_manager_add_actor (GlideStageManager *manager,
 			       GlideActor *actor)
 {
   GlideSlide *current_slide;
   gfloat x, y;
+  
+  g_return_if_fail (GLIDE_IS_STAGE_MANAGER (manager));
+  g_return_if_fail (GLIDE_IS_ACTOR (actor));
+
   glide_actor_set_stage_manager (actor, manager);
   
   current_slide = glide_document_get_nth_slide (manager->priv->document,