[glide] Start adding documentation section contents

From: Robert Carr <racarr src gnome org>
To: commits-list gnome org
Cc:
Subject: [glide] Start adding documentation section contents
Date: Fri, 7 May 2010 19:36:11 +0000 (UTC)
commit f24abf660262c1348276f2bdb7217cc0726ce058
Author: Robert Carr <racarr Valentine localdomain>
Date:   Fri May 7 14:46:27 2010 -0400

    Start adding documentation section contents

 docs/reference/glide-docs.sgml       |    2 +-
 libglide/glide-actor.c               |    6 ++-
 libglide/glide-animation-manager.c   |    6 +++
 libglide/glide-cairo-util.c          |    6 +++
 libglide/glide-debug.h               |    6 +++
 libglide/glide-dirs.c                |    5 ++
 libglide/glide-document.c            |    6 +++
 libglide/glide-gtk-util.c            |    5 ++
 libglide/glide-image.c               |    8 ++++
 libglide/glide-inspector-actor.c     |    5 ++
 libglide/glide-inspector-animation.c |    5 ++
 libglide/glide-inspector-image.c     |    6 +++
 libglide/glide-inspector-notebook.c  |    6 +++
 libglide/glide-inspector-shape.c     |    6 +++
 libglide/glide-inspector-slide.c     |    6 +++
 libglide/glide-inspector-text.c      |    6 +++
 libglide/glide-inspector-window.c    |    4 ++
 libglide/glide-json-util.c           |    7 +++
 libglide/glide-manipulator.c         |    6 +++
 libglide/glide-pdf-exporter.c        |    6 +++
 libglide/glide-shape.c               |    6 ++-
 libglide/glide-slide-box.c           |    6 +++
 libglide/glide-slide-button.c        |    6 +++
 libglide/glide-slide.c               |    5 ++
 libglide/glide-stage-manager.c       |    6 +++
 libglide/glide-text.c                |    9 +----
 libglide/glide-theme.c               |   69 ++++++++++++++++++++++++++++++++--
 libglide/glide-undo-manager.c        |    6 +++
 libglide/glide-window.c              |    5 ++
 29 files changed, 216 insertions(+), 15 deletions(-)
---
diff --git a/docs/reference/glide-docs.sgml b/docs/reference/glide-docs.sgml
index ba48419..b2b53f8 100644
--- a/docs/reference/glide-docs.sgml
+++ b/docs/reference/glide-docs.sgml
@@ -16,7 +16,7 @@
 
   <part id="api">
     <title>Glide API Reference </title>
-    <para>This is documentation for the libglide API, containing the Glide application logic</para>
+    <para>This is documentation for the libglide API</para>
     <xi:include href="xml/glide.xml"/>
     <chapter id="actors">
       <title>Glide Actor Types</title>
diff --git a/libglide/glide-actor.c b/libglide/glide-actor.c
index 425ec9b..c61bf99 100644
--- a/libglide/glide-actor.c
+++ b/libglide/glide-actor.c
@@ -15,7 +15,11 @@
  * You should have received a copy of the GNU General Public License along
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/**
+ * SECTION:glide-actor
+ * @short_description: Base abstract class for all visual document elements.
+ *
+ */
  
 #include <glib/gi18n.h>
 #include "glide-actor.h"
diff --git a/libglide/glide-animation-manager.c b/libglide/glide-animation-manager.c
index a0c675b..97ec82f 100644
--- a/libglide/glide-animation-manager.c
+++ b/libglide/glide-animation-manager.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-animation-manager
+ * @short_description: Manages and performs animations.
+ *
+ */
+
 #include <gobject/gvaluecollector.h>
 #include <glib.h>
 #include <string.h>
diff --git a/libglide/glide-cairo-util.c b/libglide/glide-cairo-util.c
index 8e365f6..a0b4a2b 100644
--- a/libglide/glide-cairo-util.c
+++ b/libglide/glide-cairo-util.c
@@ -15,6 +15,12 @@
  * You should have received a copy of the GNU General Public License along
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** 
+ * SECTION:glide-cairo-util
+ * @short_description: Glide cairo utility functions.
+ *
+ */
+
 
 
 #include "glide-cairo-util.h"
diff --git a/libglide/glide-debug.h b/libglide/glide-debug.h
index f29a950..ec4bf8d 100644
--- a/libglide/glide-debug.h
+++ b/libglide/glide-debug.h
@@ -15,6 +15,12 @@
  * Copyright (C) Robert Carr 2009 <carrr rpi edu>
  */
 
+/**
+ * SECTION:glide-debug
+ * @short_description: Glide debugging macros.
+ *
+ */
+
 #ifndef _GLIDE_DEBUG_H
 #define _GLIDE_DEBUG_H
 
diff --git a/libglide/glide-dirs.c b/libglide/glide-dirs.c
index 90b827d..877b711 100644
--- a/libglide/glide-dirs.c
+++ b/libglide/glide-dirs.c
@@ -15,6 +15,11 @@
  * You should have received a copy of the GNU General Public License along
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/**
+ * SECTION:glide-dirs
+ * @short_description: Utility functions for obtaining Glide data directories.
+ *
+ */
 
 #include "glide-dirs.h"
 
diff --git a/libglide/glide-document.c b/libglide/glide-document.c
index d2c54d1..864b30b 100644
--- a/libglide/glide-document.c
+++ b/libglide/glide-document.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-document
+ * @short_description: Representation of a loaded document file
+ *
+ */
+
 #include <stdlib.h>
  
 #include "glide-document.h"
diff --git a/libglide/glide-gtk-util.c b/libglide/glide-gtk-util.c
index cb683e0..381fd31 100644
--- a/libglide/glide-gtk-util.c
+++ b/libglide/glide-gtk-util.c
@@ -15,6 +15,11 @@
  * You should have received a copy of the GNU General Public License along
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/** 
+ * SECTION:glide-gtk-util
+ * @short_description: Glide GTK+ utility functions.
+ *
+ */
 
 
 #include "glide-gtk-util.h"
diff --git a/libglide/glide-image.c b/libglide/glide-image.c
index 2378167..dd28f2d 100644
--- a/libglide/glide-image.c
+++ b/libglide/glide-image.c
@@ -16,6 +16,14 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-image
+ * @short_description: An actor for displaying image files.
+ *
+ * #GlideImage is an actor which displays an image file, using
+ * GdkPixbuf as the file loader.
+ */
+
 
 #include "glide-image.h"
 #include "glide-image-priv.h"
diff --git a/libglide/glide-inspector-actor.c b/libglide/glide-inspector-actor.c
index eae6531..3d73bdd 100644
--- a/libglide/glide-inspector-actor.c
+++ b/libglide/glide-inspector-actor.c
@@ -15,6 +15,11 @@
  * You should have received a copy of the GNU General Public License along
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/**
+ * SECTION:glide-inspector-actor
+ * @short_description: An inspector page for general actor properties.
+ *
+ */
 
 #include "glide-inspector-actor.h"
 #include "glide-inspector-actor-priv.h"
diff --git a/libglide/glide-inspector-animation.c b/libglide/glide-inspector-animation.c
index edc339e..3c1239d 100644
--- a/libglide/glide-inspector-animation.c
+++ b/libglide/glide-inspector-animation.c
@@ -15,6 +15,11 @@
  * You should have received a copy of the GNU General Public License along
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/**
+ * SECTION:glide-inspector-animation
+ * @short_description: An inspector page for animation settings.
+ *
+ */
 
 #include "glide-inspector-animation.h"
 #include "glide-inspector-animation-priv.h"
diff --git a/libglide/glide-inspector-image.c b/libglide/glide-inspector-image.c
index f38b5e4..cb6d4c0 100644
--- a/libglide/glide-inspector-image.c
+++ b/libglide/glide-inspector-image.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-inspector-image
+ * @short_description: An inspector page for image actors.
+ *
+ */
+
 #include "glide-inspector-image.h"
 #include "glide-inspector-image-priv.h"
 
diff --git a/libglide/glide-inspector-notebook.c b/libglide/glide-inspector-notebook.c
index 90d3fee..5dba76c 100644
--- a/libglide/glide-inspector-notebook.c
+++ b/libglide/glide-inspector-notebook.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-inspector-notebook
+ * @short_description: The Glide inspector widget.
+ *
+ */
+
 #include "glide-inspector-notebook.h"
 #include "glide-inspector-notebook-priv.h"
 
diff --git a/libglide/glide-inspector-shape.c b/libglide/glide-inspector-shape.c
index 06bc44f..08d02b3 100644
--- a/libglide/glide-inspector-shape.c
+++ b/libglide/glide-inspector-shape.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-inspector-shape
+ * @short_description: An inspector page for shape actors.
+ *
+ */
+
 #include "glide-inspector-shape.h"
 #include "glide-inspector-shape-priv.h"
 
diff --git a/libglide/glide-inspector-slide.c b/libglide/glide-inspector-slide.c
index c4c2e53..899f80f 100644
--- a/libglide/glide-inspector-slide.c
+++ b/libglide/glide-inspector-slide.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-inspector-slide
+ * @short_description: An inspector page for slide actors.
+ *
+ */
+
 #include "glide-inspector-slide.h"
 #include "glide-inspector-slide-priv.h"
 
diff --git a/libglide/glide-inspector-text.c b/libglide/glide-inspector-text.c
index 32c7354..c94f27b 100644
--- a/libglide/glide-inspector-text.c
+++ b/libglide/glide-inspector-text.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-inspector-text
+ * @short_description: An inspector page for text actors.
+ *
+ */
+
 #include "glide-inspector-text.h"
 #include "glide-inspector-text-priv.h"
 
diff --git a/libglide/glide-inspector-window.c b/libglide/glide-inspector-window.c
index f8f308c..c44b2cf 100644
--- a/libglide/glide-inspector-window.c
+++ b/libglide/glide-inspector-window.c
@@ -15,6 +15,10 @@
  * You should have received a copy of the GNU General Public License along
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/**
+ * SECTION:glide-inspector-window
+ * @short_description: A floating window containing the inspector.
+ */
 
 #include "glide-inspector-notebook.h"
 #include "glide-inspector-window.h"
diff --git a/libglide/glide-json-util.c b/libglide/glide-json-util.c
index 92b7cb9..8696aa0 100644
--- a/libglide/glide-json-util.c
+++ b/libglide/glide-json-util.c
@@ -16,6 +16,13 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/** 
+ * SECTION:glide-json-util
+ * @short_description: Glide json utility functions.
+ *
+ */
+
+
 
 #include "glide-json-util.h"
 
diff --git a/libglide/glide-manipulator.c b/libglide/glide-manipulator.c
index da129bd..d32dcb8 100644
--- a/libglide/glide-manipulator.c
+++ b/libglide/glide-manipulator.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-manipulator
+ * @short_description: An actor for transforming a target actor.
+ *
+ */
+
  
 #include <glib/gi18n.h>
 #include "glide-manipulator.h"
diff --git a/libglide/glide-pdf-exporter.c b/libglide/glide-pdf-exporter.c
index 517d88a..4ccf5fd 100644
--- a/libglide/glide-pdf-exporter.c
+++ b/libglide/glide-pdf-exporter.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-pdf-exporter
+ * @short_description: An exporter for Portable Document Format (PDF) files.
+ *
+ */
+
 
 #include "glide-pdf-exporter.h"
 #include "glide-actor.h"
diff --git a/libglide/glide-shape.c b/libglide/glide-shape.c
index 98c5384..522e1fa 100644
--- a/libglide/glide-shape.c
+++ b/libglide/glide-shape.c
@@ -15,7 +15,11 @@
  * You should have received a copy of the GNU General Public License along
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
+/**
+ * SECTION:glide-shape
+ * @short_description: An actor for displaying and editing 2D Vector Shapes.
+ *
+ */
 
 #include "glide-shape.h"
 #include "glide-shape-priv.h"
diff --git a/libglide/glide-slide-box.c b/libglide/glide-slide-box.c
index a0fed10..db4c82c 100644
--- a/libglide/glide-slide-box.c
+++ b/libglide/glide-slide-box.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-slide-box
+ * @short_description: Displays a list of slide preview buttons.
+ *
+ */
+
 #include "glide-slide-box.h"
 #include "glide-slide-box-priv.h"
 
diff --git a/libglide/glide-slide-button.c b/libglide/glide-slide-button.c
index 667e348..1691ee2 100644
--- a/libglide/glide-slide-button.c
+++ b/libglide/glide-slide-button.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-slide-button
+ * @short_description: A button containing a slide thumbnail.
+ *
+ */
+
 #include "glide-slide-button.h"
 #include "glide-slide-button-priv.h"
 
diff --git a/libglide/glide-slide.c b/libglide/glide-slide.c
index ca2ce82..655fa57 100644
--- a/libglide/glide-slide.c
+++ b/libglide/glide-slide.c
@@ -15,6 +15,11 @@
  * You should have received a copy of the GNU General Public License along
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/**
+ * SECTION:glide-slide
+ * @short_description: A container actor representing a slide in a document.
+ *
+ */
 
 #include <math.h>
 
diff --git a/libglide/glide-stage-manager.c b/libglide/glide-stage-manager.c
index 98a1acb..69397c8 100644
--- a/libglide/glide-stage-manager.c
+++ b/libglide/glide-stage-manager.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-stage-manager
+ * @short_description: Orchestrates editing and presenting actions.
+ *
+ */
+
  
 #include <glib/gi18n.h>
 #include "glide-stage-manager.h"
diff --git a/libglide/glide-text.c b/libglide/glide-text.c
index c4bd958..4ea49bb 100644
--- a/libglide/glide-text.c
+++ b/libglide/glide-text.c
@@ -42,19 +42,12 @@
  */
 
 /**
- * SECTION:clutter-text
+ * SECTION:glide-text
  * @short_description: An actor for displaying and editing text
  *
  * #GlideText is an actor that displays custom text using Pango
  * as the text rendering engine.
  *
- * #GlideText also allows inline editing of the text if the
- * actor is set editable using glide_text_set_editable().
- *
- * Selection using keyboard or pointers can be enabled using
- * glide_text_set_selectable().
- *
- * #GlideText is available since Clutter 1.0
  */
 
 /* TODO: undo/redo hooks? */
diff --git a/libglide/glide-theme.c b/libglide/glide-theme.c
index f168b52..43ac832 100644
--- a/libglide/glide-theme.c
+++ b/libglide/glide-theme.c
@@ -15,6 +15,11 @@
  * You should have received a copy of the GNU General Public License along
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/**
+ * SECTION:glide-theme
+ * @short_description: A representation of a loaded theme file.
+ *
+ */
 
 #include <stdlib.h>
  
@@ -251,42 +256,98 @@ glide_theme_init (GlideTheme *d)
   glide_theme_make_working_dir (d);
 }
 
+/**
+ * glide_theme_new:
+ * @path: The path containing the theme definition file.
+ *
+ * Constructs a new #GlideTheme from the definition file
+ * at @path.
+ *
+ * Return value: The newly constructed #GlideTheme.
+ */
 GlideTheme *
-glide_theme_new (const gchar *name)
+glide_theme_new (const gchar *path)
 {
   return g_object_new (GLIDE_TYPE_THEME,
-		       "path", name,
+		       "path", path,
 		       NULL);
 }
 
+/**
+ * glide_theme_get_default_background:
+ * @theme: A #GlideTheme.
+ *
+ * Returns the default background for @theme.
+ *
+ * Return value: The default background of @theme.
+ */
 const gchar *
 glide_theme_get_default_background (GlideTheme *theme)
 {
+  g_return_val_if_fail (GLIDE_IS_THEME (theme), NULL);
   return theme->priv->default_background;
 }
 
+/**
+ * glide_theme_get_name:
+ * @theme: A #GlideTheme.
+ *
+ * Returns the name for @theme.
+ *
+ * Return value: The name of @theme.
+ */
 const gchar *
 glide_theme_get_name (GlideTheme *theme)
 {
+  g_return_val_if_fail (GLIDE_IS_THEME (theme), NULL);
   return theme->priv->name;
 }
 
+/**
+ * glide_theme_get_path:
+ * @theme: A #GlideTheme.
+ *
+ * Returns the path of the definition file for @theme.
+ *
+ * BUG: Themes should probably be resources of some sort, imported in to the file.
+ *
+ * Return value: The path of @theme.
+ */
 const gchar *
 glide_theme_get_path (GlideTheme *theme)
 {
+  g_return_val_if_fail (GLIDE_IS_THEME (theme), NULL);
   return theme->priv->path;
 }
 
+/**
+ * glide_theme_get_default_fontname:
+ * @theme: A #GlideTheme
+ *
+ * Returns the default fontname for @theme.
+ *
+ * Return value: The default fontname of @theme.
+ */
 const gchar *
 glide_theme_get_default_fontname (GlideTheme *theme)
 {
+  g_return_val_if_fail (GLIDE_IS_THEME (theme), NULL);
   return theme->priv->default_fontname;
 }
 
+/**
+ * glide_theme_get_default_color:
+ * @theme: A #GlideTheme
+ * @color: A #ClutterColor in which the return value will be stored.
+ *
+ * Returns the default color for @theme through @color.
+ *
+ */
 void
-glide_theme_get_default_color (GlideTheme *theme, ClutterColor *c)
+glide_theme_get_default_color (GlideTheme *theme, ClutterColor *color)
 {
-  *c = theme->priv->default_color;
+  g_return_if_fail (GLIDE_IS_THEME (theme));
+  *color = theme->priv->default_color;
 }
 
 
diff --git a/libglide/glide-undo-manager.c b/libglide/glide-undo-manager.c
index 8352703..36e5c57 100644
--- a/libglide/glide-undo-manager.c
+++ b/libglide/glide-undo-manager.c
@@ -16,6 +16,12 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:glide-undo-manager
+ * @short_description: Orchestrates and manages undo actions for a document.
+ *
+ */
+
 
 
 #include "glide-undo-manager.h"
diff --git a/libglide/glide-window.c b/libglide/glide-window.c
index 5cae408..fb09379 100644
--- a/libglide/glide-window.c
+++ b/libglide/glide-window.c
@@ -15,6 +15,11 @@
  * You should have received a copy of the GNU General Public License along
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+/**
+ * SECTION:glide-window
+ * @short_description: Main editor window.
+ *
+ */
  
 #include <glib/gi18n.h>
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]