more commenting.

2008-01-21  Thomas Thurman  <tthurman@gnome.org>

     * src/ui/theme.[ch]: more commenting.



svn path=/trunk/; revision=3524

ChangeLog

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

src/ui/theme.c

@@ -1661,7 +1661,7 @@ debug_print_tokens (PosToken *tokens,
  * Tokenises an expression.
  *
  * \param      expr        The expression
- * \param[out] token_p     The resulting tokens
+ * \param[out] tokens_p    The resulting tokens
  * \param[out] n_tokens_p  The number of resulting tokens
  * \param[out] err  set to the problem if there was a problem
  *
@@ -1794,6 +1794,10 @@ pos_tokenize (const char  *expr,
   return FALSE;
 }
 
+/**
+ * The type of a PosExpr: either integer, double, or an operation.
+ * \ingroup parser
+ */
 typedef enum
 {
   POS_EXPR_INT,
@@ -1802,8 +1806,14 @@ typedef enum
 } PosExprType;
 
 /**
+ * Type and value of an expression in a parsed sequence. We don't
+ * keep expressions in a tree; if this is of type POS_EXPR_OPERATOR,
+ * the arguments of the operator will be in the array positions
+ * immediately preceding and following this operator; they cannot
+ * themselves be operators.
  *
  * \bug operator is char; it should really be of PosOperatorType.
+ * \ingroup parser
  */
 typedef struct
 {
@@ -2218,10 +2228,11 @@ pos_eval_get_variable (PosToken                  *t,
  * \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
+ * \ingroup parser
  */
 static gboolean
 pos_eval_helper (PosToken                   *tokens,
@@ -2398,6 +2409,7 @@ pos_eval_helper (PosToken                   *tokens,
  * \return  True if we evaluated the expression successfully; false otherwise.
  *
  * \bug Shouldn't spec be const?
+ * \ingroup parser
  */
 static gboolean
 pos_eval (MetaDrawSpec              *spec,
@@ -3969,6 +3981,15 @@ meta_draw_op_list_contains (MetaDrawOpList    *op_list,
   return FALSE;
 }
 
+/**
+ * Constructor for a MetaFrameStyle.
+ *
+ * \param parent  The parent style. Data not filled in here will be
+ *                looked for in the parent style, and in its parent
+ *                style, and so on.
+ *
+ * \return The newly-constructed style.
+ */
 MetaFrameStyle*
 meta_frame_style_new (MetaFrameStyle *parent)
 {
@@ -3988,6 +4009,12 @@ meta_frame_style_new (MetaFrameStyle *parent)
   return style;
 }
 
+/**
+ * Increases the reference count of a frame style.
+ * If the style is NULL, this is a no-op.
+ *
+ * \param style  The style.
+ */
 void
 meta_frame_style_ref (MetaFrameStyle *style)
 {

src/ui/theme.h

@@ -72,6 +72,8 @@ typedef enum
 
 /**
  * Various parameters used to calculate the geometry of a frame.
+ * They are used inside a MetaFrameStyle.
+ * This corresponds closely to the <frame_geometry> tag in a theme file.
  *
  * \bug button_sizing isn't really necessary, because we could easily say
  * that if button_aspect is zero, the height and width are fixed values.
@@ -148,12 +150,10 @@ struct _MetaFrameLayout
 };
 
 /**
- * The size of a button (FIXME: In general? Or on one frame?).
+ * The computed size of a button (really just a way of tying its
+ * visible and clickable areas together).
  * The reason for two different rectangles here is Fitts' law & maximized
  * windows; see bug #97703 for more details.
- *
- * \bug In general? Or on one frame? FIXME
- * \bug Bugs should be hyperlinked: talk to doxygen people
  */
 struct _MetaButtonSpace
 {
@@ -295,33 +295,40 @@ struct _MetaDrawInfo
   const MetaFrameGeometry *fgeom;
 };
 
+/**
+ * A drawing operation in our simple vector drawing language.
+ */
 typedef enum
 {
-  /* Basic drawing */
+  /** Basic drawing-- line */
   META_DRAW_LINE,
+  /** Basic drawing-- rectangle */
   META_DRAW_RECTANGLE,
+  /** Basic drawing-- arc */
   META_DRAW_ARC,
 
-  /* Clip to a rectangle */
+  /** Clip to a rectangle */
   META_DRAW_CLIP,
   
   /* Texture thingies */
-  META_DRAW_TINT, /* just a filled rectangle with alpha */
+
+  /** Just a filled rectangle with alpha */
+  META_DRAW_TINT,
   META_DRAW_GRADIENT,
   META_DRAW_IMAGE,
   
-  /* GTK theme engine stuff */
+  /** GTK theme engine stuff */
   META_DRAW_GTK_ARROW,
   META_DRAW_GTK_BOX,
   META_DRAW_GTK_VLINE,
 
-  /* App's window icon */
+  /** App's window icon */
   META_DRAW_ICON,
-  /* App's window title */
+  /** App's window title */
   META_DRAW_TITLE,
-  /* a draw op list */
+  /** a draw op list */
   META_DRAW_OP_LIST,
-  /* tiled draw op list */
+  /** tiled draw op list */
   META_DRAW_TILE
 } MetaDrawType;
 
@@ -347,6 +354,11 @@ typedef enum
   POS_OP_MIN
 } PosOperatorType;
 
+/**
+ * A token, as output by the tokeniser.
+ *
+ * \ingroup tokenizer
+ */
 typedef struct
 {
   PosTokenType type;
@@ -374,11 +386,14 @@ typedef struct
 } PosToken;
 
 /**
+ * A computed expression in our simple vector drawing language.
+ * While it appears to take the form of a tree, this is actually
+ * merely a list; concerns such as precedence of operators are
+ * currently recomputed on every recalculation.
  *
  * 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 parser
- * \ingroup tokenizer
  */
 typedef struct _MetaDrawSpec
 {
@@ -397,7 +412,10 @@ typedef struct _MetaDrawSpec
   /** Does the expression contain any variables? */
   gboolean constant : 1;
 } MetaDrawSpec;
-  
+
+/**
+ * A single drawing operation in our simple vector drawing language.
+ */
 struct _MetaDrawOp
 {
   MetaDrawType type;
@@ -543,6 +561,14 @@ struct _MetaDrawOp
   } data;
 };
 
+/**
+ * A list of MetaDrawOp objects. Maintains a reference count.
+ * Grows as necessary and allows the allocation of unused spaces
+ * to keep reallocations to a minimum.
+ *
+ * \bug Do we really win anything from not using the equivalent
+ * GLib structures?
+ */
 struct _MetaDrawOpList
 {
   int refcount;
@@ -636,16 +662,39 @@ typedef enum
 } MetaFramePiece;
 
 #define N_GTK_STATES 5
+
+/**
+ * How to draw a frame in a particular state (say, a focussed, non-maximised,
+ * resizable frame). This corresponds closely to the <frame_style> tag
+ * in a theme file.
+ */
 struct _MetaFrameStyle
 {
+  /** Reference count. */
   int refcount;
+  /**
+   * Parent style.
+   * Settings which are unspecified here will be taken from there.
+   */
   MetaFrameStyle *parent;
+  /** Operations for drawing each kind of button in each state. */
   MetaDrawOpList *buttons[META_BUTTON_TYPE_LAST][META_BUTTON_STATE_LAST];
+  /** Operations for drawing each piece of the frame. */
   MetaDrawOpList *pieces[META_FRAME_PIECE_LAST];
+  /**
+   * Details such as the height and width of each edge, the corner rounding,
+   * and the aspect ratio of the buttons.
+   */
   MetaFrameLayout *layout;
-  MetaColorSpec *window_background_color; /* can be NULL to use the standard
+  /**
-                                             GTK theme engine */
+   * Background colour of the window. Only present in theme formats
-  guint8 window_background_alpha; /* 0=transparent; 255=opaque */
+   * 2 and above. Can be NULL to use the standard GTK theme engine.
+   */
+  MetaColorSpec *window_background_color;
+  /**
+   * Transparency of the window background. 0=transparent; 255=opaque.
+   */
+  guint8 window_background_alpha;
 };
 
 /* Kinds of frame...
@@ -688,7 +737,17 @@ typedef enum
   META_FRAME_FOCUS_LAST
 } MetaFrameFocus;
 
-/* One StyleSet per window type (for window types that get a frame) */
+/**
+ * How to draw frames at different times: when it's maximised or not, shaded
+ * or not, when it's focussed or not, and (for non-maximised windows), when
+ * it can be horizontally or vertically resized, both, or neither.
+ * Not all window types actually get a frame.
+ *
+ * A theme contains one of these objects for each type of window (each
+ * MetaFrameType), that is, normal, dialogue (modal and non-modal), etc.
+ *
+ * This corresponds closely to the <frame_style_set> tag in a theme file.
+ */
 struct _MetaFrameStyleSet
 {
   int refcount;
@@ -699,20 +758,47 @@ struct _MetaFrameStyleSet
   MetaFrameStyle *maximized_and_shaded_styles[META_FRAME_FOCUS_LAST];
 };
 
+/**
+ * A theme. This is a singleton class which groups all settings from a theme
+ * on disk together.
+ *
+ * \bug It is rather useless to keep the metadata fields in core, I think.
+ */
 struct _MetaTheme
 {
+  /** Name of the theme (on disk), e.g. "Crux" */
   char *name;
+  /** Path to the files associated with the theme */
   char *dirname;
+  /**
+   * Filename of the XML theme file.
+   * \bug Kept lying around for no discernable reason.
+   */
   char *filename;
+  /** Metadata: Human-readable name of the theme. */
   char *readable_name;
+  /** Metadata: Author of the theme. */
   char *author;
+  /** Metadata: Copyright holder. */
   char *copyright;
+  /** Metadata: Date of the theme. */
   char *date;
+  /** Metadata: Description of the theme. */
   char *description;
+  /** Version of the theme format. Older versions cannot use the features
+   * of newer versions even if they think they can (this is to allow forward
+   * and backward compatibility.
+   */
   guint format_version;
 
+  /** Symbol table of integer constants. */
   GHashTable *integer_constants;
+  /** Symbol table of float constants. */
   GHashTable *float_constants;
+  /**
+   * Symbol table of colour constants (hex triples, and triples
+   * plus alpha).
+   * */
   GHashTable *color_constants;
   GHashTable *images_by_filename;
   GHashTable *layouts_by_name;