some more commenting.

2008-01-18  Thomas Thurman  <tthurman@gnome.org>                                                                                                  
                                                                                                                                                  
        * src/ui/theme.[ch]: some more commenting. 

svn path=/trunk/; revision=3523

ChangeLog

@@ -1,9 +1,14 @@
+2008-01-18  Thomas Thurman  <tthurman@gnome.org>
+
+	* src/ui/theme.[ch]: some more commenting.
+	
 2008-01-16  Thomas Thurman  <tthurman@gnome.org>
 
 	* src/core/bell.c: Correct comment.
 	* src/core/main.c: Correct comment.
-	* src/core/theme.c: Much commenting; #ifdeffed-out debug code removed.
+	* src/ui/theme.c: Much commenting; #ifdeffed-out
-	* src/core/theme.h: Much commenting.
+	debug code removed.
+	* src/ui/theme.h: Much commenting.
 
 2008-01-13  Thomas Thurman  <tthurman@gnome.org>
 

src/ui/theme.c

@@ -2211,9 +2211,16 @@ pos_eval_get_variable (PosToken                  *t,
 }
 
 /**
- * foo
+ * Evaluates a sequence of tokens within a particular environment context,
+ * and returns the current value. May recur if parantheses are found.
  *
- * \param tokens
+ * \param tokens  A list of tokens to evaluate.
+ * \param n_tokens  How many tokens are in the list.
+ * \param env  The environment context in which to evaluate the expression.
+ * \param[out] result  The current value of the expression
+ * \bug Yes, we really do reparse the expression every time it's evaluated.
+ *      We should keep the parse tree around all the time and just
+ *      run the new values through it.
  * \bug FIXME write this
  */
 static gboolean
@@ -2377,6 +2384,21 @@ pos_eval_helper (PosToken                   *tokens,
  *
  *   so very not worth fooling with bison, yet so very painful by hand.
  */
+/**
+ * Evaluates an expression.
+ *
+ * \param spec  The expression to evaluate.
+ * \param env   The environment context to evaluate the expression in.
+ * \param[out] val_p  The integer value of the expression; if the expression
+ *                    is of type float, this will be rounded. If we return
+ *                    FALSE because the expression is invalid, this will be
+ *                    zero.
+ * \param[out] err    The error, if anything went wrong.
+ *
+ * \return  True if we evaluated the expression successfully; false otherwise.
+ *
+ * \bug Shouldn't spec be const?
+ */
 static gboolean
 pos_eval (MetaDrawSpec              *spec,
           const MetaPositionExprEnv *env,

src/ui/theme.h

@@ -373,14 +373,29 @@ typedef struct
   } d;
 } PosToken;
 
+/**
+ *
+ * Created by meta_draw_spec_new(), destroyed by meta_draw_spec_free().
+ * pos_eval() fills this with ...FIXME. Are tokens a tree or a list?
+ * \bug FIXME finish filling this in
+ * \ingroup tokenizer
+ */
 typedef struct _MetaDrawSpec
 {
+  /**
+   * If this spec is constant, this is the value of the constant;
+   * otherwise it is zero.
+   */
   int value;
   
+  /** A list of tokens in the expression. */
   PosToken *tokens;
+
+  /** How many tokens are in the tokens list. */
   int n_tokens;
 
-  gboolean constant : 1; /* Does the expression contain any variables? */
+  /** Does the expression contain any variables? */
+  gboolean constant : 1;
 } MetaDrawSpec;
   
 struct _MetaDrawOp