gegl r2969 - in trunk: . gegl/graph gegl/operation gegl/process

[martinn svn gnome org]

Author: martinn
Date: Wed Mar 18 19:36:49 2009
New Revision: 2969
URL: http://svn.gnome.org/viewvc/gegl?rev=2969&view=rev

Log:
Add documentation in form of comments

Apply patch from Henrik Akesson that adds documentation to the graph
parts of the GEGL core in form of comments.

Modified:
   trunk/ChangeLog
   trunk/gegl/graph/gegl-node.c
   trunk/gegl/graph/gegl-visitor.c
   trunk/gegl/operation/gegl-operation.c
   trunk/gegl/process/gegl-cr-visitor.c
   trunk/gegl/process/gegl-eval-mgr.c
   trunk/gegl/process/gegl-eval-mgr.h
   trunk/gegl/process/gegl-have-visitor.c
   trunk/gegl/process/gegl-prepare-visitor.c

Modified: trunk/gegl/graph/gegl-node.c
==============================================================================
--- trunk/gegl/graph/gegl-node.c	(original)
+++ trunk/gegl/graph/gegl-node.c	Wed Mar 18 19:36:49 2009
@@ -801,6 +801,10 @@
     priv->eval_mgr = gegl_eval_mgr_new (node, pad);
 }
 
+/* Will set the eval_mgr's roi to the supplied roi if defined, otherwise
+ * it will use the node's bounding box. Then the gegl_eval_mgr_apply will
+ * be called.
+ */
 static GeglBuffer *
 gegl_node_apply_roi (GeglNode            *self,
                      const gchar         *output_pad_name,
@@ -1646,6 +1650,9 @@
   gegl_operation_context_destroy (context);
 }
 
+/* Creates, sets up and returns a new context for the node, or just returns it
+ * if it is already set up. Also adds it to an internal hash table.
+ */
 GeglOperationContext *
 gegl_node_add_context (GeglNode *self,
                        gpointer  context_id)

Modified: trunk/gegl/graph/gegl-visitor.c
==============================================================================
--- trunk/gegl/graph/gegl-visitor.c	(original)
+++ trunk/gegl/graph/gegl-visitor.c	Wed Mar 18 19:36:49 2009
@@ -182,6 +182,7 @@
   return g_hash_table_lookup (self->hash, visitable);
 }
 
+/* resets the object's data (list of visits and visitable statuses) */
 void gegl_visitor_reset (GeglVisitor   *self)
 {
   if (self->visits_list)
@@ -192,6 +193,9 @@
   g_hash_table_remove_all (self->hash);
 }
 
+/* Inserts the visitable into the object's hash table of visitables with the
+ * object as a key and a new GeglVisitInfo (zero initialised) as object
+ */
 static void
 insert (GeglVisitor   *self,
         GeglVisitable *visitable)
@@ -206,6 +210,7 @@
     }
 }
 
+/* Returns TRUE if a GeglVisitable has already been visited */
 static gboolean
 get_visited (GeglVisitor   *self,
              GeglVisitable *visitable)
@@ -311,10 +316,14 @@
   g_return_if_fail (GEGL_IS_VISITOR (self));
   g_return_if_fail (GEGL_IS_VISITABLE (visitable));
 
+  /* sets up the structures that keeps track of the */
   init_dfs_traversal (self, visitable);
   dfs_traverse (self, visitable);
 }
 
+/* Recursively (depth first) sets up the structure (hash) that keeps track of
+ * if a visitable's status
+ */
 static void
 init_dfs_traversal (GeglVisitor   *self,
                     GeglVisitable *visitable)
@@ -322,6 +331,7 @@
   GSList *depends_on_list;
   GSList *llink;
 
+  /* add the visitable to the list */
   insert (self, visitable);
   depends_on_list = gegl_visitable_depends_on (visitable);
   llink           = depends_on_list;
@@ -331,6 +341,9 @@
       GeglVisitable *visitable  = llink->data;
       GeglVisitInfo *visit_info = lookup (self, visitable);
 
+      /* if the visitable doesn't have a visit_info,
+       * then it needs to be initialised
+       */
       if (!visit_info)
         init_dfs_traversal (self, visitable);
 
@@ -340,6 +353,9 @@
   g_slist_free (depends_on_list);
 }
 
+/* Recursively (depth first) traverses the visitables and call's their
+ * accept methods
+ */
 static void
 dfs_traverse (GeglVisitor   *self,
               GeglVisitable *visitable)
@@ -354,6 +370,7 @@
     {
       GeglVisitable *visitable = llink->data;
 
+      /* if the visitable has not yet been visitied then visit it */
       if (!get_visited (self, visitable))
         dfs_traverse (self, visitable);
 
@@ -362,7 +379,11 @@
 
   g_slist_free (depends_on_list);
 
+  /* trigger the actual visit (call the visitable's accept method that will
+   * call the visitable's visit method (c.f. the visitor pattern)
+   */
   gegl_visitable_accept (visitable, self);
+  /* mark the visitable as already visited*/
   set_visited (self, visitable, TRUE);
 }
 
@@ -468,6 +489,9 @@
     }
 }
 
+/* should be called by extending classes when their visit_pad function
+ * is called
+ */
 void
 gegl_visitor_visit_pad (GeglVisitor *self,
                         GeglPad     *pad)
@@ -490,6 +514,9 @@
   self->visits_list = g_slist_prepend (self->visits_list, pad);
 }
 
+/* should be called by extending classes when their visit_node function
+ * is called
+ */
 void
 gegl_visitor_visit_node (GeglVisitor *self,
                          GeglNode    *node)
@@ -505,6 +532,7 @@
     klass->visit_node (self, node);
 }
 
+/* adds the visiting node to the list of visits */
 static void
 visit_node (GeglVisitor *self,
             GeglNode    *node)

Modified: trunk/gegl/operation/gegl-operation.c
==============================================================================
--- trunk/gegl/operation/gegl-operation.c	(original)
+++ trunk/gegl/operation/gegl-operation.c	Wed Mar 18 19:36:49 2009
@@ -123,6 +123,9 @@
   return klass->process (operation, context, output_pad, result);
 }
 
+/* Calls an extending class' get_bound_box method if defined otherwise
+ * just returns a zero-initiliased bouding box
+ */
 GeglRectangle
 gegl_operation_get_bounding_box (GeglOperation *self)
 {
@@ -228,6 +231,7 @@
   klass->attach (self);
 }
 
+/* Calls the prepare function on the operation that extends this base class */
 void
 gegl_operation_prepare (GeglOperation *self)
 {

Modified: trunk/gegl/process/gegl-cr-visitor.c
==============================================================================
--- trunk/gegl/process/gegl-cr-visitor.c	(original)
+++ trunk/gegl/process/gegl-cr-visitor.c	Wed Mar 18 19:36:49 2009
@@ -53,6 +53,7 @@
 {
 }
 
+/* sets the context's result_rect and refs */
 static void
 gegl_cr_visitor_visit_node (GeglVisitor *self,
                             GeglNode    *node)

Modified: trunk/gegl/process/gegl-eval-mgr.c
==============================================================================
--- trunk/gegl/process/gegl-eval-mgr.c	(original)
+++ trunk/gegl/process/gegl-eval-mgr.c	Wed Mar 18 19:36:49 2009
@@ -123,14 +123,6 @@
 }
 
 
-/**
- * gegl_eval_mgr_apply:
- * @self: a #GeglEvalMgr.
- * @root:
- * @property_name:
- *
- * Update this property.
- **/
 GeglBuffer *
 gegl_eval_mgr_apply (GeglEvalMgr *self)
 {
@@ -156,14 +148,18 @@
 
   g_object_ref (root);
 
+  /* do the necessary set-up work (all using depth first traversal) */
   switch (self->state)
     {
       case 0:
+        /* Set up the node's context and "needed rectangle"*/
         gegl_visitor_reset (self->prepare_visitor);
         gegl_visitor_dfs_traverse (self->prepare_visitor, GEGL_VISITABLE (root));
+        /* No idea why there is a second call */
         gegl_visitor_reset (self->prepare_visitor);
         gegl_visitor_dfs_traverse (self->prepare_visitor, GEGL_VISITABLE (root));
       case 1:
+        /* sets up the node's rect (bounding box) */
         gegl_visitor_reset (self->have_visitor);
         gegl_visitor_dfs_traverse (self->have_visitor, GEGL_VISITABLE (root));
       case 2:
@@ -172,6 +168,7 @@
         self->state = 2;
      }
 
+  /* set up the root node */
   if (self->roi.width == -1 &&
       self->roi.height == -1)
     {
@@ -181,6 +178,7 @@
   gegl_node_set_need_rect (root, context_id, &self->roi);
   root->is_root = TRUE;
 
+  /* set up the context's rectangle (breadth first traversal) */
   gegl_visitor_reset (self->cr_visitor);
   gegl_visitor_bfs_traverse (self->cr_visitor, GEGL_VISITABLE (root));
 
@@ -196,6 +194,7 @@
     }
 #endif
 
+  /* now let's do the real work */
   gegl_visitor_reset (self->eval_visitor);
   if (pad)
     {
@@ -225,6 +224,7 @@
       g_value_unset (&value);
     }
 
+  /* do the clean up */
   gegl_visitor_reset (self->finish_visitor);
   gegl_visitor_dfs_traverse (self->finish_visitor, GEGL_VISITABLE (root));
 

Modified: trunk/gegl/process/gegl-eval-mgr.h
==============================================================================
--- trunk/gegl/process/gegl-eval-mgr.h	(original)
+++ trunk/gegl/process/gegl-eval-mgr.h	Wed Mar 18 19:36:49 2009
@@ -51,7 +51,7 @@
                               up the contexts on the nodes.
                          */
 
-  /* we keep these objects around, they are to expensive to throw away */
+  /* we keep these objects around, they are too expensive to throw away */
   GeglVisitor *prepare_visitor;
   GeglVisitor *cr_visitor;
   GeglVisitor *eval_visitor;

Modified: trunk/gegl/process/gegl-have-visitor.c
==============================================================================
--- trunk/gegl/process/gegl-have-visitor.c	(original)
+++ trunk/gegl/process/gegl-have-visitor.c	Wed Mar 18 19:36:49 2009
@@ -51,6 +51,7 @@
 {
 }
 
+/* sets up the node's bounding box */
 static void
 gegl_have_visitor_visit_node (GeglVisitor *self,
                               GeglNode    *node)

Modified: trunk/gegl/process/gegl-prepare-visitor.c
==============================================================================
--- trunk/gegl/process/gegl-prepare-visitor.c	(original)
+++ trunk/gegl/process/gegl-prepare-visitor.c	Wed Mar 18 19:36:49 2009
@@ -51,6 +51,9 @@
 {
 }
 
+/* adds a context to the node, calls the operation's prepare method and
+ * sets the node's "needed rectangle" to an empty one
+ */
 static void
 gegl_prepare_visitor_visit_node (GeglVisitor *self,
                                  GeglNode    *node)
@@ -59,6 +62,7 @@
 
   glong          time = gegl_ticks ();
 
+  /* call the parent's class (gegl-visitor.c) visit_node function */
   GEGL_VISITOR_CLASS (gegl_prepare_visitor_parent_class)->visit_node (self, node);
 
   if (self->context_id == NULL)
@@ -86,6 +90,7 @@
 
   gegl_operation_prepare (operation);
   {
+    /* initialise the "needed rectangle" to an empty one */
     GeglRectangle empty ={0,};
     gegl_node_set_need_rect (node, self->context_id, &empty);
   }