glsl: Add doxygen comments

2 files changed, 121 insertions, 12 deletions

diff --git a/src/glsl/ast.h b/src/glsl/ast.h
index 44c31b6e62..d7bf90925c 100644
--- a/src/glsl/ast.h
+++ b/src/glsl/ast.h
@@ -33,6 +33,20 @@ struct _mesa_glsl_parse_state;
 
 struct YYLTYPE;
 
+/**
+ * \defgroup AST Abstract syntax tree node definitions
+ *
+ * An abstract syntax tree is generated by the parser.  This is a fairly
+ * direct representation of the gramma derivation for the source program.
+ * No symantic checking is done during the generation of the AST.  Only
+ * syntactic checking is done.  Symantic checking is performed by a later
+ * stage that converts the AST to a more generic intermediate representation.
+ *
+ *@{
+ */
+/**
+ * Base class of all abstract syntax tree nodes
+ */
 class ast_node {
 public:
    /* Callers of this talloc-based new need not call delete. It's
@@ -54,7 +68,14 @@ public:
       talloc_free(table);
    }
 
+   /**
+    * Print an AST node in something approximating the original GLSL code
+    */
    virtual void print(void) const;
+
+   /**
+    * Convert the AST node to the high-level intermediate representation
+    */
    virtual ir_rvalue *hir(exec_list *instructions,
 			  struct _mesa_glsl_parse_state *state);
 
@@ -91,19 +112,29 @@ public:
       this->location.column = locp.first_column;
    }
 
+   /**
+    * Source location of the AST node.
+    */
    struct {
-      unsigned source;
-      unsigned line;
-      unsigned column;
+      unsigned source;    /**< GLSL source number. */
+      unsigned line;      /**< Line number within the source string. */
+      unsigned column;    /**< Column in the line. */
    } location;
 
    exec_node link;
 
 protected:
+   /**
+    * The only constructor is protected so that only derived class objects can
+    * be created.
+    */
    ast_node(void);
 };
 
 
+/**
+ * Operators for AST expression nodes.
+ */
 enum ast_operators {
    ast_assign,
    ast_plus,        /**< Unary + operator. */
@@ -161,6 +192,9 @@ enum ast_operators {
    ast_sequence
 };
 
+/**
+ * Representation of any sort of expression.
+ */
 class ast_expression : public ast_node {
 public:
    ast_expression(int oper, ast_expression *,
@@ -651,7 +685,7 @@ public:
    ast_function *prototype;
    ast_compound_statement *body;
 };
-
+/*@}*/
 
 extern void
 _mesa_ast_to_hir(exec_list *instructions, struct _mesa_glsl_parse_state *state);
diff --git a/src/glsl/ir.h b/src/glsl/ir.h
index b3b15bb08e..909f8242a7 100644
--- a/src/glsl/ir.h
+++ b/src/glsl/ir.h
@@ -41,7 +41,31 @@ extern "C" {
 #define ARRAY_SIZE(x) (sizeof(x) / sizeof(x[0]))
 #endif
 
+/**
+ * \defgroup IR Intermediate representation nodes
+ *
+ * @{
+ */
+
+/**
+ * Class tags
+ *
+ * Each concrete class derived from \c ir_instruction has a value in this
+ * enumerant.  The value for the type is stored in \c ir_instruction::ir_type
+ * by the constructor.  While using type tags is not very C++, it is extremely
+ * convenient.  For example, during debugging you can simply inspect
+ * \c ir_instruction::ir_type to find out the actual type of the object.
+ *
+ * In addition, it is possible to use a switch-statement based on \c
+ * \c ir_instruction::ir_type to select different behavior for different object
+ * types.  For functions that have only slight differences for several object
+ * types, this allows writing very straightforward, readable code.
+ */
 enum ir_node_type {
+   /**
+    * Zero is unused so that the IR validator can detect cases where
+    * \c ir_instruction::ir_type has not been initialized.
+    */
    ir_type_unset,
    ir_type_variable,
    ir_type_assignment,
@@ -156,9 +180,12 @@ protected:
 };
 
 
+/**
+ * Variable storage classes
+ */
 enum ir_variable_mode {
-   ir_var_auto = 0,
-   ir_var_uniform,
+   ir_var_auto = 0,     /**< Function local variables and globals. */
+   ir_var_uniform,      /**< Variable declared as a uniform. */
    ir_var_in,
    ir_var_out,
    ir_var_inout,
@@ -209,6 +236,9 @@ public:
     */
    unsigned component_slots() const;
 
+   /**
+    * Delcared name of the variable
+    */
    const char *name;
 
    /**
@@ -218,11 +248,28 @@ public:
     */
    unsigned max_array_access;
 
+   /**
+    * Is the variable read-only?
+    *
+    * This is set for variables declared as \c const, shader inputs,
+    * and uniforms.
+    */
    unsigned read_only:1;
    unsigned centroid:1;
    unsigned invariant:1;
 
+   /**
+    * Storage class of the variable.
+    *
+    * \sa ir_variable_mode
+    */
    unsigned mode:3;
+
+   /**
+    * Interpolation mode for shader inputs / outputs
+    *
+    * \sa ir_variable_interpolation
+    */
    unsigned interpolation:2;
 
    /**
@@ -233,9 +280,13 @@ public:
     */
    unsigned array_lvalue:1;
 
-   /* ARB_fragment_coord_conventions */
+   /**
+    * \name ARB_fragment_coord_conventions
+    * @{
+    */
    unsigned origin_upper_left:1;
    unsigned pixel_center_integer:1;
+   /*@}*/
 
    /**
     * Storage location of the base of this variable
@@ -724,9 +775,22 @@ public:
 
    virtual ir_expression *clone(void *mem_ctx, struct hash_table *ht) const;
 
+   /**
+    * Attempt to constant-fold the expression
+    *
+    * If the expression cannot be constant folded, this method will return
+    * \c NULL.
+    */
    virtual ir_constant *constant_expression_value();
 
+   /**
+    * Determine the number of operands used by an expression
+    */
    static unsigned int get_num_operands(ir_expression_operation);
+
+   /**
+    * Determine the number of operands used by an expression
+    */
    unsigned int get_num_operands() const
    {
       return get_num_operands(operation);
@@ -813,6 +877,9 @@ public:
       return callee->function_name();
    }
 
+   /**
+    * Get the function signature bound to this function call
+    */
    ir_function_signature *get_callee()
    {
       return callee;
@@ -977,11 +1044,11 @@ public:
  * Texture sampling opcodes used in ir_texture
  */
 enum ir_texture_opcode {
-   ir_tex,		/* Regular texture look-up */
-   ir_txb,		/* Texture look-up with LOD bias */
-   ir_txl,		/* Texture look-up with explicit LOD */
-   ir_txd,		/* Texture look-up with partial derivatvies */
-   ir_txf		/* Texel fetch with explicit LOD */
+   ir_tex,		/**< Regular texture look-up */
+   ir_txb,		/**< Texture look-up with LOD bias */
+   ir_txl,		/**< Texture look-up with explicit LOD */
+   ir_txd,		/**< Texture look-up with partial derivatvies */
+   ir_txf		/**< Texel fetch with explicit LOD */
 };
 
 
@@ -1384,9 +1451,17 @@ private:
    ir_constant(void);
 };
 
+/*@}*/
+
+/**
+ * Apply a visitor to each IR node in a list
+ */
 void
 visit_exec_list(exec_list *list, ir_visitor *visitor);
 
+/**
+ * Validate invariants on each IR node in a list
+ */
 void validate_ir_tree(exec_list *instructions);
 
 /**