[gegl/soc-2011-warp: 11/23] GeglPath: docs + some coding style

[Michael Murà <mmure src gnome org>]

commit cdc09d6c1d8c28049584bc96c29570d3598789ff
Author: Michael Murà <batolettre gmail com>
Date:   Tue Jun 28 20:33:00 2011 +0200

    GeglPath: docs + some coding style

 gegl/property-types/gegl-path.c |   27 ++++++++++++++++++++-------
 gegl/property-types/gegl-path.h |   11 ++++++-----
 2 files changed, 26 insertions(+), 12 deletions(-)
---
diff --git a/gegl/property-types/gegl-path.c b/gegl/property-types/gegl-path.c
index 60def55..22017dd 100644
--- a/gegl/property-types/gegl-path.c
+++ b/gegl/property-types/gegl-path.c
@@ -175,6 +175,7 @@ static InstructionInfo knot_types[64]= /* reserve space for a total of up to 64
   {'L',  2, "line to",              flatten_copy},
   {'C',  6, "curve to",             flatten_curve},
 
+  /* each point is relative to the previous */
   {'m',  2, "rel move to",          flatten_rel_copy},
   {'l',  2, "rel line to",          flatten_rel_copy},
   {'c',  6, "rel curve to",         flatten_rel_copy},
@@ -671,11 +672,6 @@ gegl_path_clear (GeglPath *vector)
   priv->tail = NULL;
 }
 
-/* -1 means last */
-
-/* pos = 0, pushes the existing 0 if any to 1,
- * passing -1 means add at end
- */
 void
 gegl_path_insert_node (GeglPath           *vector,
                        gint                pos,
@@ -1332,6 +1328,16 @@ gegl_path_list_append (GeglPathList *head,
   return head;
 }
 
+/**
+ * gegl_path_list_append_item:
+ * @head: the list to append item on
+ * @type: the type of the new item
+ * @res:  return a pointer to the new item
+ * @tail: the tail of the list
+ *
+ * Append a new item in the list.
+ * @tail can be NULL. Providing it will accelerate the operation.
+ */
 static GeglPathList *
 gegl_path_list_append_item  (GeglPathList  *head,
                              gchar          type,
@@ -1347,7 +1353,7 @@ gegl_path_list_append_item  (GeglPathList  *head,
 
   if (iter)
     {
-      /* the +3 is padding, +1 was excpected to be sufficient */
+      /* the +3 is padding, +1 was expected to be sufficient */
       iter->next =
         g_slice_alloc0 (sizeof (gpointer) + sizeof (gchar) + sizeof (gfloat)*2 *(info->n_items+3)/2);
       iter->next->d.type = type;
@@ -1355,7 +1361,7 @@ gegl_path_list_append_item  (GeglPathList  *head,
     }
   else /* creating new path */
     {
-      /* the +3 is padding, +1 was excpected to be sufficient */
+      /* the +3 is padding, +1 was expected to be sufficient */
       head =
         g_slice_alloc0 (sizeof (gpointer) + sizeof (gchar) + sizeof (gfloat)*2 *(info->n_items+3)/2);
       head->d.type = type;
@@ -1367,6 +1373,13 @@ gegl_path_list_append_item  (GeglPathList  *head,
   return head;
 }
 
+/**
+ * gegl_path_list_flatten:
+ * @matrix: a #GeglMatrix3 transformation matrix
+ * @original: the #GeglPathList to flatten
+ *
+ * Flatten the provided GeglPathList
+ */
 static GeglPathList *
 gegl_path_list_flatten (GeglMatrix3  *matrix,
                         GeglPathList *original)
diff --git a/gegl/property-types/gegl-path.h b/gegl/property-types/gegl-path.h
index 3fa4518..33520c4 100644
--- a/gegl/property-types/gegl-path.h
+++ b/gegl/property-types/gegl-path.h
@@ -276,7 +276,7 @@ typedef void LP *GeglNodeFunction RP LP const GeglPathItem *node,
  * @user_data: user data to pass to the function (in addition to the GeglPathItem).
  *
  * Execute a provided function for every node in the path (useful for
- * drawing and otherwise traversing  a path.)
+ * drawing and otherwise traversing a path.)
  */
 void                 gegl_path_foreach        (GeglPath        *path,
                                                GeglNodeFunction each_item,
@@ -311,9 +311,10 @@ void                 gegl_path_clear          (GeglPath    *path);
  * @node: pointer to a structure describing the GeglPathItem we want to store
  *
  * Insert the new node @node at position @pos in @path.
+ * if @pos = -1, the node is added in the last position.
  */
-void                 gegl_path_insert_node    (GeglPath    *path,
-                                               gint         pos,
+void                 gegl_path_insert_node    (GeglPath           *path,
+                                               gint                pos,
                                                const GeglPathItem *node);
 /**
  * gegl_path_replace_node:
@@ -323,8 +324,8 @@ void                 gegl_path_insert_node    (GeglPath    *path,
  *
  * Replaces the exiting node at position @pos in @path.
  */
-void                 gegl_path_replace_node   (GeglPath    *path,
-                                               gint         pos,
+void                 gegl_path_replace_node   (GeglPath           *path,
+                                               gint                pos,
                                                const GeglPathItem *node);
 /**
  * gegl_path_remove_node: