[glide] Start on doc+guards for document

[Robert Carr <racarr src gnome org>]

commit c149fcce062e52f937674343f3453939cdc56ad3
Author: Robert Carr <racarr Valentine localdomain>
Date:   Fri May 7 16:45:45 2010 -0400

    Start on doc+guards for document

 libglide/glide-document.c     |  237 +++++++++++++++++++++++++++++++++++------
 libglide/glide-pdf-exporter.c |    2 +-
 2 files changed, 207 insertions(+), 32 deletions(-)
---
diff --git a/libglide/glide-document.c b/libglide/glide-document.c
index 864b30b..593fe7d 100644
--- a/libglide/glide-document.c
+++ b/libglide/glide-document.c
@@ -352,10 +352,25 @@ glide_document_append_slide (GlideDocument *document)
   return s;
 }
 
+/**
+ * glide_document_insert_slide:
+ * @document: A #GlideDocument
+ * @after: The slide index to insert after.
+ *
+ * Creates and inserts a new #GlideSlide in @document, after
+ * the slide at index @after.
+ *
+ * Return value: The newly created #GlideSlide
+ */
 GlideSlide *
 glide_document_insert_slide (GlideDocument *document, gint after)
 {
-  GlideSlide *s = glide_slide_new (document);
+  GlideSlide *s;
+  
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), NULL);
+  g_return_val_if_fail (after < g_list_length (document->priv->slides), NULL);
+
+  s = glide_slide_new (document);
 
   document->priv->slides = g_list_insert (document->priv->slides, s, after+1);
   
@@ -367,10 +382,23 @@ glide_document_insert_slide (GlideDocument *document, gint after)
   return s;
 }
 
+/**
+ * glide_document_remove_slide:
+ * @document: A #GlideDocument
+ * @slide: The slide to remove.
+ *
+ * Removes the slide at @index from @document.
+ *
+ */
 void
 glide_document_remove_slide (GlideDocument *document, gint slide)
 {
-  GlideSlide *s = g_list_nth_data (document->priv->slides, slide);
+  GlideSlide *s;
+  
+  g_return_if_fail (GLIDE_IS_DOCUMENT (document));
+  g_return_if_fail (slide < g_list_length (document->priv->slides));
+
+  s = g_list_nth_data (document->priv->slides, slide);
   document->priv->slides = g_list_remove (document->priv->slides, s);
   
   glide_document_update_slide_indices (document);
@@ -408,12 +436,24 @@ glide_document_json_obj_set_slides (GlideDocument *document, JsonObject *obj)
   
 }
 
+/**
+ * glide_document_serialize: 
+ * @document: A #GlideDocument
+ *
+ * Serializes the contents of @document to JSON.
+ *
+ * Return value: A #JsonNode containing the serialized contents of @document.
+ */
 JsonNode *
 glide_document_serialize(GlideDocument *document)
 {
-  JsonNode *node = json_node_new (JSON_NODE_OBJECT);
+  JsonNode *node;
   JsonObject *obj;
   
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), NULL);
+  
+  node = json_node_new (JSON_NODE_OBJECT);
+  
   obj = json_object_new ();
   json_node_set_object (node, obj);
   
@@ -423,29 +463,68 @@ glide_document_serialize(GlideDocument *document)
   return node;
 }
 
+/**
+ * glide_document_get_height:
+ * @document: A #Returns
+ *
+ * GlideDocument the height of @document.
+ *
+ * Return value: The height of @document.
+ */
 gint 
 glide_document_get_height (GlideDocument *document)
 {
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), 0);
   return document->priv->height;
 }
 
+/**
+ * glide_document_get_width:
+ * @document: A #GlideDocument
+ *
+ * Returns the width of @document.
+ *
+ * Return value: The width of @document.
+ */
 gint 
 glide_document_get_width (GlideDocument *document)
 {
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), 0);
   return document->priv->width;
 }
 
+/**
+ * glide_document_get_size:
+ * @document: A #GlideDocument.
+ * @width: Location to write the width of @document.
+ * @height: Location to write the height of @document.
+ *
+ * Returns the size of @document through @width and @height.
+ *
+ */
 void
 glide_document_get_size (GlideDocument *document, gint *width, gint *height)
 {
+  g_return_if_fail (GLIDE_IS_DOCUMENT (document));
   *width = document->priv->width;
   *height = document->priv->height;
 }
 
+/**
+ * glide_document_resize:
+ * @document: A #GlideDocument
+ * @width: The new width in pixels.
+ * @height: The new height in pixels.
+ *
+ * Resizes @document and it's contents for display at @width by @height.
+ *
+ */
 void
 glide_document_resize (GlideDocument *document, gint width, gint height)
 {
   GList *s;
+  
+  g_return_if_fail (GLIDE_IS_DOCUMENT (document));
 
   document->priv->width = width;
   document->priv->height = height;
@@ -460,48 +539,87 @@ glide_document_resize (GlideDocument *document, gint width, gint height)
     }
 }
 
-
+/**
+ * glide_document_get_dirty:
+ * @document: A #GlideDocument
+ *
+ * Gets the value of the dirty flag for @document.
+ *
+ * Return value: %TRUE if @document has unsaved changes. False otherwise.
+ */
 gboolean
-glide_document_get_dirty (GlideDocument *d)
+glide_document_get_dirty (GlideDocument *document)
 {
-  return d->priv->dirty;
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), FALSE);
+  return document->priv->dirty;
 }
 
+/**
+ * glide_document_set_dirty:
+ * @document: A #GlideDocument
+ * @dirty: The new dirty value for @GlideDocument
+ *
+ * Sets the @dirty flag on @document, marking if @document
+ * has unsaved changes.
+ *
+ */
 void
-glide_document_set_dirty (GlideDocument *d, gboolean dirty)
+glide_document_set_dirty (GlideDocument *document, gboolean dirty)
 {
-  d->priv->dirty = dirty;
-  g_object_notify (G_OBJECT (d), "dirty");
+  g_return_if_fail (GLIDE_IS_DOCUMENT (document));
+
+  document->priv->dirty = dirty;
+  g_object_notify (G_OBJECT (document), "dirty");
 }
 
+/**
+ * glide_document_write_archive:
+ * @document: A #GlideDocument
+ *
+ * Saves the archive file for @document at the path
+ * of @document.
+ */
 void
-glide_document_write_archive (GlideDocument *d)
+glide_document_write_archive (GlideDocument *document)
 {
-  gchar *command = g_strdup_printf("tar -cjspf %s %s",
-				   d->priv->path,
-				   d->priv->working_path);
+  gchar *command;
+  
+  g_return_if_fail (GLIDE_IS_DOCUMENT (document));
+
+  command = g_strdup_printf("tar -cjspf %s %s",
+				   document->priv->path,
+				   document->priv->working_path);
   g_message("command %s", command);
   
   system (command);
 }
 
+/**
+ * glide_document_write_json:
+ * @document: A #GlideDocument
+ *
+ * Saves the JSON file for @document in the working path of
+ * @document.
+ */
 void
-glide_document_write_json (GlideDocument *d)
+glide_document_write_json (GlideDocument *document)
 {
   GError *e = NULL;
   JsonNode *node;
   JsonGenerator *gen;
   gchar *json_path;
   
-  node = glide_document_serialize (d);
+  g_return_if_fail (GLIDE_IS_DOCUMENT (document);
+  
+  node = glide_document_serialize (document);
   gen = json_generator_new ();
   g_object_set (gen, "pretty", TRUE, NULL);
   
   json_generator_set_root (gen, node);
   
   if (!d->priv->working_path)
-    glide_document_make_working_dir (d);
-  json_path = g_strdup_printf("%s/document.json",d->priv->working_path);
+    glide_document_make_working_dir (document);
+  json_path = g_strdup_printf("%s/document.json",document->priv->working_path);
   
   // TODO: Error
   json_generator_to_file (gen, json_path, &e);
@@ -526,16 +644,30 @@ glide_document_extract_archive (GlideDocument *d,
   g_free (command);
 }
 
+/**
+ * glide_document_load_archive:
+ * @document: A #GlideDocument
+ * @filename: Path to a Glide archive file to open.
+ *
+ * Opens a Glide archive file, and returns a #JsonParser for
+ * the contained document.
+ *
+ * Return value: A newly created #JsonParser for @filename.
+ */
 JsonParser *
-glide_document_load_archive (GlideDocument *d,
+glide_document_load_archive (GlideDocument *document,
 			     const gchar *filename)
 {
-  JsonParser *p = json_parser_new ();
+  JsonParser *p;
   GError *e = NULL;
   gchar *json_file;
+  
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), NULL);
+  
+  p = json_parser_new ();
 
-  glide_document_make_working_dir (d);
-  glide_document_extract_archive (d, filename);
+  glide_document_make_working_dir (document);
+  glide_document_extract_archive (document, filename);
   
   json_file = g_strdup_printf("%s/document.json",d->priv->working_path);
 
@@ -556,23 +688,36 @@ glide_document_load_archive (GlideDocument *d,
     }
   g_free (json_file);
   
-  glide_document_set_path (d, filename);
+  glide_document_set_path (document, filename);
   
   return p;
 }
 
 //TODO: Name sanitization
+/**
+ * glide_document_add_resource:
+ * @document: A #GlideDocument
+ * @filename: The path to the resource to add
+ *
+ * Adds @filename to @document as a resource, and returns
+ * the resource name. The file will now be embedded in the
+ * document archive and is accessible by resource name.
+ *
+ * Return value: The resource name for @filename in @document.
+ */
 gchar *
-glide_document_add_resource (GlideDocument *d, const gchar *filename)
+glide_document_add_resource (GlideDocument *document, const gchar *filename)
 {
   GFile *from, *to;
   gchar *basename, *to_path;
   
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), NULL);
+  
   if (!g_path_is_absolute (filename))
     return g_strdup (filename);
   
   basename = g_path_get_basename (filename);
-  to_path = g_strdup_printf("%s/resources/%s", d->priv->working_path,
+  to_path = g_strdup_printf("%s/resources/%s", document->priv->working_path,
 			    basename);
 
   from = g_file_new_for_path (filename);
@@ -589,23 +734,53 @@ glide_document_add_resource (GlideDocument *d, const gchar *filename)
   return basename;
 }
 
+/**
+ * glide_document_get_resource_path:
+ * @document: A #GlideDocument
+ * @resource_name: The resource name
+ *
+ * Returns a file path for @resource_name in the extracted
+ * document archive.
+ *
+ * Return value: The path for @resource_name.
+ */
 gchar *
-glide_document_get_resource_path (GlideDocument *d,
+glide_document_get_resource_path (GlideDocument *document,
 				  const gchar *resource_name)
 {
-  return g_strdup_printf("%s/resources/%s",d->priv->working_path,
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), NULL);
+  return g_strdup_printf("%s/resources/%s",document->priv->working_path,
 			 resource_name);
 }
 
+/**
+ * glide_document_get_theme:
+ * @document: A #GlideDocument
+ *
+ * Returns the theme for @document.
+ *
+ * Return value: The #GlideTheme for @document.
+ */
 GlideTheme *
-glide_document_get_theme (GlideDocument *d)
+glide_document_get_theme (GlideDocument *document)
 {
-  return d->priv->theme;
+  g_return_val_if_fail (GLIDE_IS_DOCUMENT (document), NULL);
+  return document->priv->theme;
 }
 
+/**
+ * glide_document_set_theme:
+ * @document: A #GlideDocument
+ * @theme: The #GlideTheme to use for @document
+ *
+ * Sets the theme for @document to @theme
+ */
 void
-glide_document_set_theme (GlideDocument *d, GlideTheme *theme)
+glide_document_set_theme (GlideDocument *document, GlideTheme *theme)
 {
-  d->priv->theme = theme;
-  g_object_notify (G_OBJECT (d), "theme");
+  g_return_if_fail (GLIDE_IS_DOCUMENT (document));
+  g_return_if_fail (GLIDE_IS_THEME (theme));
+
+  document->priv->theme = theme;
+  g_object_notify (G_OBJECT (document), "theme");
 }
diff --git a/libglide/glide-pdf-exporter.c b/libglide/glide-pdf-exporter.c
index 65e5c27..11141cb 100644
--- a/libglide/glide-pdf-exporter.c
+++ b/libglide/glide-pdf-exporter.c
@@ -87,6 +87,6 @@ void
 glide_pdf_exporter_export (GlideDocument *document)
 {
   g_return_if_fail (GLIDE_IS_DOCUMENT (document));
-
+  
   glide_gtk_util_show_save_dialog (G_CALLBACK (glide_pdf_exporter_response_callback), document);
 }