[glide] Undo manager docs and guards

[Robert Carr <racarr src gnome org>]

commit 434dde969a0e8dcb99c4e0e133b1aa6b8f2326ff
Author: Robert Carr <racarr Valentine localdomain>
Date:   Fri May 7 15:36:30 2010 -0400

    Undo manager docs and guards

 docs/reference/glide-sections.txt |   12 +-
 libglide/glide-undo-manager.c     |  213 ++++++++++++++++++++++++++++++++-----
 2 files changed, 193 insertions(+), 32 deletions(-)
---
diff --git a/docs/reference/glide-sections.txt b/docs/reference/glide-sections.txt
index 84383ce..e8737c0 100644
--- a/docs/reference/glide-sections.txt
+++ b/docs/reference/glide-sections.txt
@@ -539,7 +539,6 @@ GLIDE_INSPECTOR_SHAPE_GET_CLASS
 <SECTION>
 <FILE>glide-undo-manager</FILE>
 <TITLE>GlideUndoManager</TITLE>
-GlideUndoManagerPrivate
 GlideUndoManager
 GlideUndoManagerClass
 GlideUndoInfo
@@ -549,17 +548,18 @@ glide_undo_manager_new
 glide_undo_manager_append_info
 glide_undo_manager_undo
 glide_undo_manager_redo
-glide_undo_manager_start_actor_action
-glide_undo_manager_end_actor_action
-glide_undo_manager_start_slide_action
-glide_undo_manager_end_slide_action
 glide_undo_manager_append_delete
 glide_undo_manager_append_insert
-glide_undo_manager_cancel_actor_action
 glide_undo_manager_get_can_undo
 glide_undo_manager_get_can_redo
 glide_undo_manager_get_undo_label
 glide_undo_manager_get_redo_label
+glide_undo_manager_start_actor_action
+glide_undo_manager_cancel_actor_action
+glide_undo_manager_end_actor_action
+glide_undo_manager_start_slide_action
+glide_undo_manager_end_slide_action
+
 <SUBSECTION Standard>
 GLIDE_UNDO_MANAGER
 GLIDE_IS_UNDO_MANAGER
diff --git a/libglide/glide-undo-manager.c b/libglide/glide-undo-manager.c
index 36e5c57..5b4d04c 100644
--- a/libglide/glide-undo-manager.c
+++ b/libglide/glide-undo-manager.c
@@ -197,26 +197,46 @@ glide_undo_actor_action_redo_callback (GlideUndoManager *undo_manager,
   return TRUE;
 }
 
+/**
+ * glide_undo_manager_start_slide_action:
+ * @manager: A #GlideUndoManager.
+ * @slide: A #GlideSlide to record
+ * @label: The undo label for this action.
+ *
+ * BUG: An equivalent of glide_undo_manager_start_actor_action to hack around
+ * serialization API mess in #GlideSlide.
+ */
 void
 glide_undo_manager_start_slide_action (GlideUndoManager *manager,
-				       GlideSlide *s,
+				       GlideSlide *slide,
 				       const gchar *label)
 {
-  manager->priv->recorded_actor = (ClutterActor *)s;
+  manager->priv->recorded_actor = (ClutterActor *)slide;
   manager->priv->recorded_label = g_strdup (label);
   
-  manager->priv->recorded_background = g_strdup (glide_slide_get_background (s));
-  glide_slide_get_color (s, &manager->priv->recorded_color);
+  manager->priv->recorded_background = g_strdup (glide_slide_get_background (slide));
+  glide_slide_get_color (slide, &manager->priv->recorded_color);
 }
 
+/**
+ * glide_undo_manager_end_slide_action:
+ * @manager: A #GlideUndoManager
+ * @slide: A #GlideSlide
+ *
+ * See glide_undo_manager_start_slide_action()
+ *
+ */
 void
 glide_undo_manager_end_slide_action (GlideUndoManager *manager,
-				     GlideSlide *a)
+				     GlideSlide *slide)
 {
   GlideUndoInfo *info;
   GlideUndoSlideData *data;
   
-  if (manager->priv->recorded_actor != (ClutterActor *)a)
+  g_return_if_fail (GLIDE_IS_UNDO_MANAGER (manager));
+  g_return_if_fail (GLIDE_IS_SLIDE (slide));
+  
+  if (manager->priv->recorded_actor != (ClutterActor *)slide)
     {
       g_warning ("Error, mismatched undo manager start/end slide actions.");
       return;
@@ -231,54 +251,92 @@ glide_undo_manager_end_slide_action (GlideUndoManager *manager,
   info->label = manager->priv->recorded_label;
   info->user_data = data;
   
-  data->slide = (GlideSlide *)g_object_ref (G_OBJECT (a));
+  data->slide = (GlideSlide *)g_object_ref (G_OBJECT (slide));
   data->old_color = manager->priv->recorded_color;
   data->old_background = manager->priv->recorded_background;
   
-  glide_slide_get_color (a, &data->new_color);
-  data->new_background = g_strdup (glide_slide_get_background (a));
+  glide_slide_get_color (slide, &data->new_color);
+  data->new_background = g_strdup (glide_slide_get_background (slide));
   
   glide_undo_manager_append_info (manager, info);
 }
 
+/**
+ * glide_undo_manager_start_actor_action:
+ * @manager: A #GlideUndoManager
+ * @actor: A #GlideActor to record
+ * @label: The undo label for this action
+ *
+ * Begins recording an undo action for an actor by snapshotting it's state
+ * using glide_actor_serialize(). When balanced by a call to glide_undo_manager_end_actor_action()
+ * an undo action representing the changes to @actor between these calls will be appended to
+ * @manager.
+ *
+ */
 void
 glide_undo_manager_start_actor_action (GlideUndoManager *manager,
-				       GlideActor *a,
+				       GlideActor *actor,
 				       const gchar *label)
 {
   JsonNode *anode;
-  manager->priv->recorded_actor = (ClutterActor *)a;
   
-  anode = glide_actor_serialize (a);
+  g_return_if_fail (GLIDE_IS_UNDO_MANAGER (manager));
+  g_return_if_fail (GLIDE_IS_ACTOR (actor));
+  
+  manager->priv->recorded_actor = (ClutterActor *)actor;
+  
+  anode = glide_actor_serialize (actor);
   manager->priv->recorded_state = json_node_get_object (anode);
   
   manager->priv->recorded_label = g_strdup (label);
 }
 
+/**
+ * glide_undo_manager_cancel_actor_action:
+ * @manager: A #GlideUndoManager
+ *
+ * Cancels the recording of an actor action previously started
+ * with glide_undo_manager_start_actor_action() .
+ *
+ */
 void
 glide_undo_manager_cancel_actor_action (GlideUndoManager *manager)
 {
+  g_return_if_fail (GLIDE_IS_UNDO_MANAGER (manager));
+  
   manager->priv->recorded_actor = NULL;
   manager->priv->recorded_state = NULL;
   
   g_free (manager->priv->recorded_label);
 }
 
+/**
+ * glide_undo_manager_end_actor_action:
+ * @manager: A #GlideUndoManager
+ * @actor: A #GlideActor, matching a balanced call to glide_undo_manager_start_actor_action().
+ *
+ * Finishes recording an actor action as started by glide_undo_manager_start_actor_action().
+ *
+ */
+
 void
 glide_undo_manager_end_actor_action (GlideUndoManager *manager,
-				     GlideActor *a)
+				     GlideActor *actor)
 {
   GlideUndoInfo *info;
   GlideUndoActorData *data;
   JsonNode *new_node;
   
-  if (manager->priv->recorded_actor != (ClutterActor *)a)
+  g_return_if_fail (GLIDE_IS_UNDO_MANAGER (manager));
+  g_return_if_fail (GLIDE_IS_ACTOR (actor));
+  
+  if (manager->priv->recorded_actor != (ClutterActor *)actor)
     {
       g_warning ("Error, mismatched undo manager start/end actor actions.");
       return;
     }
   
-  new_node = glide_actor_serialize (a);
+  new_node = glide_actor_serialize (actor);
 
   info = g_malloc (sizeof (GlideUndoInfo));
   data = g_malloc (sizeof (GlideUndoActorData));
@@ -290,22 +348,33 @@ glide_undo_manager_end_actor_action (GlideUndoManager *manager,
   info->user_data = data;
 
   
-  data->actor = (ClutterActor *)g_object_ref (G_OBJECT (a));
+  data->actor = (ClutterActor *)g_object_ref (G_OBJECT (actor));
   data->old_state = manager->priv->recorded_state;
   data->new_state = json_node_get_object (new_node);
   
   glide_undo_manager_append_info (manager, info);
 }
 
+/**
+ * glide_undo_manager_append_delete:
+ * @manager: A #GlideUndoManager
+ * @a: The deleted actor
+ *
+ * Appends a new undo action to @manager for deleting @actor
+ *
+ */
 void
 glide_undo_manager_append_delete (GlideUndoManager *manager,
-				  GlideActor *a)
+				  GlideActor *actor)
 {
   GlideUndoInfo *info;
   GlideUndoDeleteActorData *data;
   ClutterActor *parent;
   
-  parent = clutter_actor_get_parent (CLUTTER_ACTOR (a));
+  g_return_if_fail (GLIDE_IS_UNDO_MANAGER (manager));
+  g_return_if_fail (GLIDE_IS_ACTOR (actor));
+  
+  parent = clutter_actor_get_parent (CLUTTER_ACTOR (actor));
   if (!parent)
     {
       g_warning ("glide_undo_manager_append_delete: no parent.");
@@ -321,21 +390,32 @@ glide_undo_manager_append_delete (GlideUndoManager *manager,
   info->label = g_strdup("Delete object");
   info->user_data = data;
   
-  data->actor = (ClutterActor *)g_object_ref (a);
+  data->actor = (ClutterActor *)g_object_ref (actor);
   data->parent = g_object_ref (parent);
   
   glide_undo_manager_append_info (manager, info);
 }
 
+/**
+ * glide_undo_manager_append_insert:
+ * @manager: A #GlideUndoManager
+ * @a: The inserted actor
+ *
+ * Appends a new undo action to @manager for inserting @actor
+ *
+ */
 void
 glide_undo_manager_append_insert (GlideUndoManager *manager,
-				  GlideActor *a)
+				  GlideActor *actor)
 {
   GlideUndoInfo *info;
   GlideUndoDeleteActorData *data;
   ClutterActor *parent;
+
+  g_return_if_fail (GLIDE_IS_UNDO_MANAGER (manager));
+  g_return_if_fail (GLIDE_IS_ACTOR (actor));
   
-  parent = clutter_actor_get_parent (CLUTTER_ACTOR (a));
+  parent = clutter_actor_get_parent (CLUTTER_ACTOR (actor));
   if (!parent)
     {
       g_warning ("glide_undo_manager_append_delete: no parent.");
@@ -351,7 +431,7 @@ glide_undo_manager_append_insert (GlideUndoManager *manager,
   info->label = g_strdup("Insert object");
   info->user_data = data;
   
-  data->actor = (ClutterActor *)g_object_ref (a);
+  data->actor = (ClutterActor *)g_object_ref (actor);
   data->parent = g_object_ref (parent);
   
   glide_undo_manager_append_info (manager, info);
@@ -394,6 +474,13 @@ glide_undo_manager_class_init (GlideUndoManagerClass *klass)
   g_type_class_add_private (object_class, sizeof(GlideUndoManagerPrivate));
 }
 
+/**
+ * glide_undo_manager_new:
+ *
+ * Creates a new #GlideUndoManager.
+ *
+ * Return value: The newly allocated #GlideUndoManager.
+ */
 GlideUndoManager *
 glide_undo_manager_new ()
 {
@@ -401,10 +488,23 @@ glide_undo_manager_new ()
 		       NULL);
 }
 
+/**
+ * glide_undo_manager_append_info:
+ * @manager: A #GlideUndoManager
+ * @info: A #GlideUndoInfo to append.
+ *
+ * Appends @info to the list of undo's for @manager as the most recent
+ * action.
+ *
+ */
 void
 glide_undo_manager_append_info (GlideUndoManager *manager, GlideUndoInfo *info)
 {
-  GList *t = g_list_next (manager->priv->position);
+  GList *t;
+  
+  g_return_if_fail (GLIDE_IS_UNDO_MANAGER (manager));
+  
+  t = g_list_next (manager->priv->position);
   while (t)
     t = glide_undo_manager_free_undo_info (t);
   if (manager->priv->position)
@@ -425,10 +525,21 @@ glide_undo_manager_append_info (GlideUndoManager *manager, GlideUndoInfo *info)
 }
 
 // TODO: Handle failed redo/undos.
+/**
+ * glide_undo_manager_redo:
+ * @manager: A #GlideUndoManager
+ *
+ * Performs the last redo action for @manager and updates
+ * the undo position.
+ *
+ * Return value: %TRUE on success, %FALSE on failure.
+ */
 gboolean
 glide_undo_manager_redo (GlideUndoManager *manager)
 {
   GlideUndoInfo *info;
+
+  g_return_val_if_fail (GLIDE_IS_UNDO_MANAGER (manager), FALSE);
   
   if (!manager->priv->position->next)
     return FALSE;
@@ -440,12 +551,22 @@ glide_undo_manager_redo (GlideUndoManager *manager)
 
   return info->redo_callback (manager, info);
 }
-
+/**
+ * glide_undo_manager_undo:
+ * @manager: A #GlideUndoManager
+ *
+ * Performs the last undo action for @manager and updates
+ * the undo position.
+ *
+ * Return value: %TRUE on success, %FALSE on failure.
+ */
 gboolean
 glide_undo_manager_undo (GlideUndoManager *manager)
 {
   GlideUndoInfo *info;
 
+  g_return_val_if_fail (GLIDE_IS_UNDO_MANAGER (manager), FALSE);
+
   if (!manager->priv->position->data)
     return FALSE;
   else
@@ -457,29 +578,69 @@ glide_undo_manager_undo (GlideUndoManager *manager)
   return info->undo_callback (manager, info);
 }
 
+/**
+ * glide_undo_manager_get_can_undo:
+ * @manager: A #GlideUndoManager
+ *
+ * Returns whether @manager has available undo actions.
+ *
+ * Return value: %TRUE if @manager has available undo actions, %FALSE otherwise.
+ */
 gboolean 
 glide_undo_manager_get_can_undo (GlideUndoManager *manager)
 {
+  g_return_val_if_fail (GLIDE_IS_UNDO_MANAGER (manager), FALSE);
   return (manager->priv->position && manager->priv->position->data != NULL);
 }
 
+/**
+ * glide_undo_manager_get_can_redo:
+ * @manager: A #GlideUndoManager
+ *
+ * Returns whether @manager has available redo actions.
+ *
+ * Return value: %TRUE if @manager has available redo actions, %FALSE otherwise.
+ */
 gboolean 
 glide_undo_manager_get_can_redo (GlideUndoManager *manager)
 {
+  g_return_val_if_fail (GLIDE_IS_UNDO_MANAGER (manager), FALSE);
   return (manager->priv->position && manager->priv->position->next != NULL);
 }
 
+/**
+ * glide_undo_manager_get_undo_label:
+ * @manager: A #GlideUndoManager
+ *
+ * Returns the label of the next undo action for @manager.
+ *
+ * Return value: The label of the next undo action.
+ */
 const gchar *
 glide_undo_manager_get_undo_label (GlideUndoManager *manager)
 {
-  GlideUndoInfo *info = (GlideUndoInfo *)manager->priv->position->data;
+  GlideUndoInfo *info;
+
+  g_return_val_if_fail (GLIDE_IS_UNDO_MANAGER (manager), NULL);
+  info  = (GlideUndoInfo *)manager->priv->position->data;
   return info->label;
 }
 
+/**
+ * glide_undo_manager_get_redo_label:
+ * @manager: A #GlideUndoManager
+ *
+ * Returns the label of the next redo action for @manager.
+ *
+ * Return value: The label of the next redo action.
+ */
 const gchar *
 glide_undo_manager_get_redo_label (GlideUndoManager *manager)
 {
-  GlideUndoInfo *info = (GlideUndoInfo *)manager->priv->position->next->data;
+  GlideUndoInfo *info;
+
+  g_return_val_if_fail (GLIDE_IS_UNDO_MANAGER (manager), NULL);
+  info  = (GlideUndoInfo *)manager->priv->position->next->data;
   return info->label;
 }