metacity r3523 - in trunk: . src/ui

[tthurman svn gnome org]

Author: tthurman
Date: Fri Jan 18 05:07:53 2008
New Revision: 3523
URL: http://svn.gnome.org/viewvc/metacity?rev=3523&view=rev

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


Modified:
   trunk/ChangeLog
   trunk/src/ui/theme.c
   trunk/src/ui/theme.h

Modified: trunk/src/ui/theme.c
==============================================================================
--- trunk/src/ui/theme.c	(original)
+++ trunk/src/ui/theme.c	Fri Jan 18 05:07:53 2008
@@ -2211,9 +2211,16 @@
 }
 
 /**
- * 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 @@
  *
  *   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,

Modified: trunk/src/ui/theme.h
==============================================================================
--- trunk/src/ui/theme.h	(original)
+++ trunk/src/ui/theme.h	Fri Jan 18 05:07:53 2008
@@ -373,14 +373,29 @@
   } 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