[glide] GlideDocument docs + API guards

[Robert Carr <racarr src gnome org>]

commit ee8f6ca7a744d93e0a580cb259c629dffca99eba
Author: Robert Carr <racarr Valentine localdomain>
Date:   Fri May 7 17:14:52 2010 -0400

    GlideDocument docs + API guards

 docs/reference/glide-sections.txt |   17 +++----
 libglide/glide-document.c         |   90 +++++++++++++++++++++++++++++++++++--
 2 files changed, 94 insertions(+), 13 deletions(-)
---
diff --git a/docs/reference/glide-sections.txt b/docs/reference/glide-sections.txt
index e8737c0..79d8405 100644
--- a/docs/reference/glide-sections.txt
+++ b/docs/reference/glide-sections.txt
@@ -52,7 +52,6 @@ GLIDE_SLIDE_GET_CLASS
 <SECTION>
 <FILE>glide-document</FILE>
 <TITLE>GlideDocument</TITLE>
-GlideDocumentPrivate
 GlideDocument
 GlideDocumentClass
 glide_document_new
@@ -61,23 +60,23 @@ glide_document_get_path
 glide_document_set_path
 glide_document_get_theme
 glide_document_set_theme
+glide_document_get_dirty
+glide_document_set_dirty
+glide_document_get_height
+glide_document_get_width
+glide_document_get_size
 glide_document_get_n_slides
 glide_document_get_nth_slide
 glide_document_append_slide
 glide_document_insert_slide
 glide_document_remove_slide
-glide_document_serialize
-glide_document_get_height
-glide_document_get_width
-glide_document_get_size
 glide_document_resize
-glide_document_get_dirty
-glide_document_set_dirty
+glide_document_add_resource
+glide_document_get_resource_path
+glide_document_serialize
 glide_document_write_archive
 glide_document_write_json
 glide_document_load_archive
-glide_document_add_resource
-glide_document_get_resource_path
 <SUBSECTION Standard>
 GLIDE_DOCUMENT
 GLIDE_IS_DOCUMENT
diff --git a/libglide/glide-document.c b/libglide/glide-document.c
index 593fe7d..a13ae69 100644
--- a/libglide/glide-document.c
+++ b/libglide/glide-document.c
@@ -278,6 +278,15 @@ glide_document_init (GlideDocument *d)
   glide_document_set_theme (d, glide_get_default_theme ());
 }
 
+/**
+ * glide_document_new:
+ * @name: The name of the new document.
+ *
+ * Creates a new document with @name.
+ * 
+ * BUG: Document names are currently meaningless?
+ * Return value: The newly created #GlideDocument.
+ */
 GlideDocument *
 glide_document_new (const gchar *name)
 {
@@ -286,41 +295,102 @@ glide_document_new (const gchar *name)
 		       NULL);
 }
 
+/**
+ * glide_document_get_name:
+ * @document: A #GlideDocument
+ *
+ * Returns the name of @document.
+ *
+ * Return value: The name of @document
+ */
 const gchar *
 glide_document_get_name (GlideDocument *document)
 {
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), NULL);
   return document->priv->name;
 }
 
+/**
+ * glide_document_get_path:
+ * @document: A #GlideDocument
+ *
+ * Returns the path of @document. Note that this is the
+ * user visible document path, and the location the
+ * archive will be saved to.
+ *
+ * Return value: The path of @document
+ */
 const gchar *
 glide_document_get_path (GlideDocument *document)
 {
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), NULL);
   return document->priv->path;
 }
 
+/**
+ * glide_document_get_working_path:
+ * @document: A #GlideDocument
+ *
+ * Returns the working_path of @document. This is
+ * the temporary path @document is currently extracted
+ * to.
+ *
+ * Return value: The working_path of @document
+ */
 const gchar *
 glide_document_get_working_path (GlideDocument *document)
 {
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), NULL);
   return document->priv->working_path;
 }
 
+/**
+ * glide_document_set_path:
+ * @document: A #GlideDocument
+ * @path: The new path for @document
+ *
+ * Sets the path of @document to @path, future writes will
+ * save the archive to this location.
+ *
+ */
 void
 glide_document_set_path (GlideDocument *document, const gchar *path)
 {
+  g_return_if_fail (GLIDE_IS_DOCUMENT (document));
   document->priv->path = g_strdup (path);
   g_object_notify (G_OBJECT (document), "path");
 }
 
+/**
+ * glide_document_get_n_slides:
+ * @document: A #GlideDocument
+ *
+ * Returns the number of slides contained in @document.
+ *
+ * Return value: The number of slides in @document.
+ */
 guint
 glide_document_get_n_slides (GlideDocument *document)
 {
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), 0);
   return g_list_length (document->priv->slides);
 }
 
+/**
+ * glide_document_get_nth_slide:
+ * @document: A #GlideDocument
+ * @n: The slide index to get.
+ *
+ * Returns the slide with index @n from @document.
+ *
+ * Return value: The slide with index @n from @document.
+ */
 GlideSlide *
 glide_document_get_nth_slide (GlideDocument *document,
 			      guint n)
 {
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), NULL);
+  g_return_val_if_fail (n < g_list_length (document->priv->slides), NULL);
   return GLIDE_SLIDE (g_list_nth_data (document->priv->slides, n));
 }
 
@@ -339,10 +409,22 @@ glide_document_update_slide_indices (GlideDocument *document)
     }
 }
 
+/**
+ * glide_document_append_slide:
+ * @document: A #GlideDocument
+ *
+ * Appends a newly created #GlideSlide to the end of @document.
+ *
+ * Return value: The newly created #GlideSlide.
+ */
 GlideSlide *
 glide_document_append_slide (GlideDocument *document)
 {
-  GlideSlide *s = glide_slide_new (document);
+  GlideSlide *s;
+  
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), NULL);
+  
+  s = glide_slide_new (document);
   
   glide_slide_set_index (s, g_list_length (document->priv->slides));
   document->priv->slides = g_list_append (document->priv->slides, s);
@@ -609,7 +691,7 @@ glide_document_write_json (GlideDocument *document)
   JsonGenerator *gen;
   gchar *json_path;
   
-  g_return_if_fail (GLIDE_IS_DOCUMENT (document);
+  g_return_if_fail (GLIDE_IS_DOCUMENT (document));
   
   node = glide_document_serialize (document);
   gen = json_generator_new ();
@@ -617,7 +699,7 @@ glide_document_write_json (GlideDocument *document)
   
   json_generator_set_root (gen, node);
   
-  if (!d->priv->working_path)
+  if (!document->priv->working_path)
     glide_document_make_working_dir (document);
   json_path = g_strdup_printf("%s/document.json",document->priv->working_path);
   
@@ -669,7 +751,7 @@ glide_document_load_archive (GlideDocument *document,
   glide_document_make_working_dir (document);
   glide_document_extract_archive (document, filename);
   
-  json_file = g_strdup_printf("%s/document.json",d->priv->working_path);
+  json_file = g_strdup_printf("%s/document.json",document->priv->working_path);
 
   json_parser_load_from_file (p, json_file, &e);
   if (e)