[glide] Document GlideActor

[Robert Carr <racarr src gnome org>]

commit 877a9685c5f7fb6043d5c7d919de701b4ff85d96
Author: Robert Carr <racarr Valentine localdomain>
Date:   Fri May 7 13:01:38 2010 -0400

    Document GlideActor

 docs/reference/glide-sections.txt |    6 +-
 libglide/glide-actor.c            |  113 ++++++++++++++++++++++++++++++++++++-
 libglide/glide.c                  |   24 ++++++++
 3 files changed, 137 insertions(+), 6 deletions(-)
---
diff --git a/docs/reference/glide-sections.txt b/docs/reference/glide-sections.txt
index 6092c03..f3d579c 100644
--- a/docs/reference/glide-sections.txt
+++ b/docs/reference/glide-sections.txt
@@ -2,6 +2,7 @@
 <FILE>glide</FILE>
 <TITLE>Initialization functions</TITLE>
 glide_get_option_group
+glide_get_default_theme
 glide_init
 </SECTION>
 
@@ -235,17 +236,16 @@ glide_animation_info_get_type
 <SECTION>
 <FILE>glide-actor</FILE>
 <TITLE>GlideActor</TITLE>
-GlideActorPrivate
 GlideActor
 GlideActorClass
 GLIDE_ACTOR_DISPLAY_NAME
 glide_actor_get_stage_manager
 glide_actor_set_stage_manager
 glide_actor_get_selected
+glide_actor_get_undo_manager
 glide_actor_serialize
-glide_actor_construct_from_json
 glide_actor_deserialize
-glide_actor_get_undo_manager
+glide_actor_construct_from_json
 glide_actor_print
 glide_actor_add_resource
 glide_actor_get_resource_path
diff --git a/libglide/glide-actor.c b/libglide/glide-actor.c
index 1243208..a4ae4a5 100644
--- a/libglide/glide-actor.c
+++ b/libglide/glide-actor.c
@@ -209,24 +209,59 @@ glide_actor_init (GlideActor *actor)
   g_free (name);
 }
 
+/**
+ * glide_actor_get_stage_manager:
+ * @actor: A #GlideActor
+ *
+ * Returns the stage manager responsible for @actor.
+ *
+ * Return value: The #GlideStageManager responsible for @actor.
+ */
 GlideStageManager *
 glide_actor_get_stage_manager (GlideActor *actor)
 {
   return actor->priv->manager;
 }
 
+/**
+ * glide_actor_get_selected:
+ * @actor: #GlideActor
+ *
+ * Returns whether an actor is the current selection.
+ *
+ * Return value: Whether @actor is the current selection.
+ */
 gboolean
 glide_actor_get_selected (GlideActor *actor)
 {
   return actor->priv->selected;
 }
 
+/**
+ * glide_actor_set_stage_manager:
+ * @actor: A #GlideActor
+ * @manager: The #GlideStageManager to set.
+ *
+ * Sets @manager to be responsible for @actor. BUG: 
+ * calling this more than once for a given actor
+ * is not permitted and it should probably be
+ * a construct only property
+ */
 void
 glide_actor_set_stage_manager (GlideActor *actor, GlideStageManager *manager)
 {
   glide_actor_set_stage_manager_real (actor, manager);
 }
 
+/**
+ * glide_actor_serialize:
+ * @actor: A #GlideActor to serialize.
+ *
+ * Serializes @actor to a #JsonNode, which can later
+ * be used by glide_actor_deserialize.
+ *
+ * Return value: A #JsonNode containing the serialized actor
+ */
 JsonNode *
 glide_actor_serialize (GlideActor *actor)
 {
@@ -245,6 +280,13 @@ glide_actor_serialize (GlideActor *actor)
   return NULL;
 }
 
+/**
+ * glide_actor_deserialize:
+ * @actor: A #GlideActor
+ * @actor_obj: A #JsonObject containing the serialized actor data.
+ *
+ * Sets the properties of @actor based on the serialized data in @actor_obj.
+ */
 void
 glide_actor_deserialize (GlideActor *actor, JsonObject *actor_obj)
 {
@@ -258,17 +300,38 @@ glide_actor_deserialize (GlideActor *actor, JsonObject *actor_obj)
   clutter_actor_set_name (CLUTTER_ACTOR (actor), glide_json_object_get_string (actor_obj, "name"));
 }
 
+/**
+ * glide_actor_print:
+ * @actor: A #GlideActor
+ * @cr: A #cairo_t to print @actor too
+ *
+ * Draw a snapshot of @actor to @cr.
+ *
+ */
 void 
-glide_actor_print (GlideActor *a, cairo_t *cr)
+glide_actor_print (GlideActor *aactor, cairo_t *cr)
 {
   GlideActorClass *klass;
   
-  klass = GLIDE_ACTOR_GET_CLASS (a);
+  klass = GLIDE_ACTOR_GET_CLASS (actor);
   if (klass->print)
-    klass->print (a, cr);
+    klass->print (aactor, cr);
 }
 
 
+/**
+ * glide_actor_construct_from_json:
+ * @manager: The #GlideStageManager to construct actors for.
+ * @actor_obj: The #JsonObject containing the actor data.
+ *
+ * Constructs a new #GlideActor from @actor_obj (of the type
+ * specified in @actor_obj).
+ *
+ * BUG: This function is mostly used for choosing which "new"
+ * function to call. and is pretty clearly a wart.
+ *
+ * Return value: The newly constructed #GlideActor, or %NULL on failure.
+ */
 GlideActor *
 glide_actor_construct_from_json (GlideStageManager *manager, 
 				 JsonObject *actor_obj)
@@ -298,30 +361,74 @@ glide_actor_construct_from_json (GlideStageManager *manager,
   return ret;
 }
 
+/**
+ * glide_actor_get_undo_manager:
+ * @actor: A #GlideActor
+ *
+ * Gets the undo manager responsible for actions
+ * performed on @actor.
+ *
+ * Return value: The #GlideUndoManager assosciated with
+ * @actor.
+ */
 GlideUndoManager *
 glide_actor_get_undo_manager (GlideActor *actor)
 {
   return glide_stage_manager_get_undo_manager (actor->priv->manager);
 }
 
+/**
+ * glide_actor_add_resource:
+ * @actor: A #GlideActor
+ * @filename: The path of the resource to add.
+ *
+ * A convenience wrapper around glide_document_add_resource()
+ *
+ * Return value: The newly imported resource name.
+ */
 gchar *
 glide_actor_add_resource (GlideActor *actor, const gchar *filename)
 {
   return glide_document_add_resource (glide_stage_manager_get_document (glide_actor_get_stage_manager (actor)), filename);
 }
 
+/**
+ * glide_actor_get_resource_path:
+ * @actor: A #GlideActor
+ * @resource_name: The name of the resource.
+ *
+ * A convenience wrapper around glide_document_get_resource_path()
+ *
+ * Return value: A path which can be used to open the file assosciated 
+ * with @resource_name
+ */
 gchar *
 glide_actor_get_resource_path (GlideActor *actor, const gchar *resource_name)
 {
   return glide_document_get_resource_path (glide_stage_manager_get_document (glide_actor_get_stage_manager (actor)), resource_name);
 }
 
+/**
+ * glide_actor_start_undo:
+ * @actor: A #GlideActor
+ * @label: The undo action label.
+ *
+ * A convenience wrapper around glide_undo_manager_start_actor_action()
+ *
+ */
 void
 glide_actor_start_undo (GlideActor *actor, const gchar *label)
 {
   glide_undo_manager_start_actor_action (glide_actor_get_undo_manager (actor), actor, label);
 }
 
+/**
+ * glide_actor_end_undo:
+ * @actor: A #GlideActor
+ *
+ * A convenience wrapper around glide_undo_manager_end_actor_action().
+ *
+ */
 void
 glide_actor_end_undo (GlideActor *actor)
 {
diff --git a/libglide/glide.c b/libglide/glide.c
index 9e76cfb..80bf7c1 100644
--- a/libglide/glide.c
+++ b/libglide/glide.c
@@ -64,6 +64,13 @@ static GOptionEntry glide_args[] = {
   {NULL,},
 };
 
+/**
+ * glide_get_option_group:
+ *
+ * Returns the #GOptionGroup to be used for parsing Glide arguments
+ *
+ * Return value: The Glide #GOptionGroup
+ */
 GOptionGroup *
 glide_get_option_group (void)
 {
@@ -118,6 +125,16 @@ glide_load_default_theme ()
   g_free (theme_path);
 }
 
+/**
+ * glide_init:
+ * @argc: A pointer to an integer containing an argument count.
+ * @argv: A pointer to the argument array, or %NULL.
+ *
+ * Initializes Glide, and parses argv. Must be called prior to
+ * other Glide functions.
+ *
+ * Return value: %TRUE on success, %FALSE on failure.
+ */
 gboolean
 glide_init (int *argc, char ***argv)
 {
@@ -129,6 +146,13 @@ glide_init (int *argc, char ***argv)
   return res;
 }
 
+/**
+ * glide_get_default_theme:
+ *
+ * Returns the default #GlideTheme to be used for new documents.
+ *
+ * Return value: The default #GlideTheme.
+ */
 GlideTheme *
 glide_get_default_theme ()
 {