Documentation improvement.

18 files changed, 691 insertions, 52 deletions

diff --git a/Makefile b/Makefile
index a3d4194..37d62bf 100644
--- a/Makefile
+++ b/Makefile
@@ -25,9 +25,11 @@ BINARIES = $(CLI_BINARY) $(GUI_BINARY)
 DOXYGEN = doxygen
 DOXYGEN_CONF = mtx.doxygen
 
-.PHONY: clean-doc clean
+.PHONY: bin all clean-doc clean
 
-all: $(BINARIES)
+bin: $(BINARIES)
+
+all: bin doc
 
 $(CLI_BINARY): $(CLI_OBJECTS)
 	$(CC) -o $(CLI_BINARY) $(CLI_OBJECTS) $(CLI_LIBS)
diff --git a/main_cli.cc b/main_cli.cc
index 2ef13c0..cb98444 100644
--- a/main_cli.cc
+++ b/main_cli.cc
@@ -18,6 +18,14 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/**
+ * \file main_cli.cc
+ * \brief CLI interface implementation.
+ * 
+ * Implements a command line interface (CLI) to the mtx engine. The CLI is
+ * based on libreadline.
+ */
+
 #include <string>
 #include <vector>
 #include <fstream>
diff --git a/main_gui.cc b/main_gui.cc
index 61c45c1..0c5e2b6 100644
--- a/main_gui.cc
+++ b/main_gui.cc
@@ -18,6 +18,14 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/**
+ * \file main_gui.cc
+ * \brief GUI interface implementation.
+ * 
+ * Implements a graphical user interface (GUI) to the mtx engine. The GUI is
+ * based on libgtkmm2.
+ */
+
 #include <stdlib.h>
 #include <gtkmm.h>
 
diff --git a/mtx.doxygen b/mtx.doxygen
index 5b4e7f3..58b602d 100644
--- a/mtx.doxygen
+++ b/mtx.doxygen
@@ -22,7 +22,7 @@ TAB_SIZE               = 8
 ALIASES                = 
 OPTIMIZE_OUTPUT_FOR_C  = NO
 OPTIMIZE_OUTPUT_JAVA   = NO
-BUILTIN_STL_SUPPORT    = NO
+BUILTIN_STL_SUPPORT    = YES
 DISTRIBUTE_GROUP_DOC   = NO
 SUBGROUPING            = YES
 EXTRACT_ALL            = YES
diff --git a/mtxdivbyzeroexception.h b/mtxdivbyzeroexception.h
index e6e1cdf..1bb6a4e 100644
--- a/mtxdivbyzeroexception.h
+++ b/mtxdivbyzeroexception.h
@@ -25,6 +25,12 @@
 
 #define MTX_DIVBYZERO_EXCEPTION_MESSAGE "division by zero"
 
+/**
+ * Division by zero exception class.
+ * 
+ * This class exists so that division by zero errors can be handled
+ * separately from other errors.
+ */
 class MtxDivByZeroException: public MtxException
 {
   public:
diff --git a/mtxentry.h b/mtxentry.h
index ebe876a..1159933 100644
--- a/mtxentry.h
+++ b/mtxentry.h
@@ -27,11 +27,25 @@
 #include "mtxhistory.h"
 #include "mtxlanguage.h"
 
+/**
+ * GUI user input object.
+ */
 class MtxEntry: public Gtk::Entry
 {
   private:
+    /**
+     * Pointer to the MtxLanguage object, used to get/set variables.
+     */
     MtxLanguage *language;
+
+    /**
+     * Pointer to the parent window.
+     */
     MtxWindow *window;
+
+    /**
+     * Object used to implement command line history.
+     */
     MtxHistory history;
 
   protected:
diff --git a/mtxexception.h b/mtxexception.h
index f185404..03b8957 100644
--- a/mtxexception.h
+++ b/mtxexception.h
@@ -25,9 +25,15 @@
 
 #define MTX_EXCEPTION_DEFAULT_MESSAGE "undefined mtx exception"
 
+/**
+ * Base class for mtx exceptions.
+ */
 class MtxException: public std::exception
 {
   protected:
+    /**
+     * Address of message returned by what().
+     */
     const char *message;
 
   public:
diff --git a/mtxexpression.cc b/mtxexpression.cc
index 10f2b1b..3c39ae2 100644
--- a/mtxexpression.cc
+++ b/mtxexpression.cc
@@ -33,10 +33,7 @@
 using namespace std;
 
 /*
- * Each line of the array indicates a level of precedence. Lines must
- * be ordered in reverse order of precedence, e.g. = has low precedence,
- * so it is placed in first line. Operators of same precedence must have
- * the same associativity (this is never checked).
+ * See mtxexpression.h.
  */
 struct mtx_operator MtxExpression::operators[][6] =
 {
@@ -229,11 +226,9 @@ MtxExpression::MtxExpression(MtxLanguage *language,
           if (!((function == MTXEXPRESSION_FUNCTION_ADDITION
                  || function == MTXEXPRESSION_FUNCTION_SUBTRACTION)
                 && first_operand.empty()))
-            expressions.push_back(new MtxExpression(language, first_operand,
-                                                    silent));
+            expressions.push_back(new MtxExpression(language, first_operand));
 
-          expressions.push_back(new MtxExpression(language, second_operand,
-                                                  silent));
+          expressions.push_back(new MtxExpression(language, second_operand));
         }
 
       else if (lexical_elements[0] == "[" && lexical_elements.back() == "]")
@@ -246,7 +241,7 @@ MtxExpression::MtxExpression(MtxLanguage *language,
 
           lexical_elements.erase(lexical_elements.begin());
           lexical_elements.erase(lexical_elements.end() - 1);
-          parseMatrix(lexical_elements, symbols, rows, columns, silent);
+          parseMatrix(lexical_elements, symbols, rows, columns);
           rationals = new MtxRational[rows * columns];
           i = 0;
 
@@ -318,7 +313,7 @@ MtxExpression::freeMatrix(vector<MtxSymbol *> &symbols) const
 void
 MtxExpression::parseMatrix(const mtx_expression_t &lexical_elements,
                            vector<MtxSymbol *> &symbols,
-                           size_t &rows, size_t &columns, bool silent) const
+                           size_t &rows, size_t &columns) const
 {
   mtx_expression_t::const_iterator iterator;
   size_t p_level, b_level, tmp_columns;
@@ -365,7 +360,7 @@ MtxExpression::parseMatrix(const mtx_expression_t &lexical_elements,
               tmp_columns = 0;
             }
 
-          symbols.push_back(new MtxExpression(language, tmp, silent));
+          symbols.push_back(new MtxExpression(language, tmp));
           tmp.clear();
         }
 
@@ -400,7 +395,7 @@ MtxExpression::parseMatrix(const mtx_expression_t &lexical_elements,
       else if (tmp_columns != columns)
         MATRIX_DIMENSIONS_ERROR(symbols);
 
-      symbols.push_back(new MtxExpression(language, tmp, silent));
+      symbols.push_back(new MtxExpression(language, tmp));
     }
 
   if (symbols.size() != (rows * columns))
diff --git a/mtxexpression.h b/mtxexpression.h
index 25eed22..16051b6 100644
--- a/mtxexpression.h
+++ b/mtxexpression.h
@@ -32,6 +32,10 @@
 #define MTXEXPRESSION_OPERATOR_NULL \
   {NULL, MTXEXPRESSION_FUNCTION_NULL, MTXEXPRESSION_ASSOCIATIVITY_NULL}
 
+/**
+ * \enum mtx_function_id
+ * \brief ID of a function/operator (e.g. assignment, addition).
+ */
 enum mtx_function_id
 {
   MTXEXPRESSION_FUNCTION_NULL,
@@ -46,6 +50,10 @@ enum mtx_function_id
   MTXEXPRESSION_FUNCTION_DIVIDE_ASSIGN
 };
 
+/**
+ * \enum mtx_operator_associativity
+ * \brief Associativity of an operator.
+ */
 enum mtx_operator_associativity
 {
   MTXEXPRESSION_ASSOCIATIVITY_NULL,
@@ -53,46 +61,153 @@ enum mtx_operator_associativity
   MTXEXPRESSION_LEFT_TO_RIGHT
 };
 
+/**
+ * An operator.
+ */
 struct mtx_operator
 {
+  /**
+   * Operator string as entered by the user.
+   */
   char *str;
+
+  /**
+   * ID of the operator.
+   */
   enum mtx_function_id id;
+
+  /**
+   * Associativity of the operator.
+   */
   enum mtx_operator_associativity associativity;
 };
 
+/**
+ * An expression.
+ * 
+ * All language expressions that are not atomic symbols (e.g. "a" or "2")
+ * are expressions which consist of a function/operator and one or more
+ * arguments. These arguments are in turn MtxExpression or MtxSymbol
+ * objects. MtxExpression objects are always nodes in the tree of symbols,
+ * whereas MtxSymbol objects are always leaves.
+ */
 class MtxExpression: public MtxSymbol
 {
   private:
+    /**
+     * Function/operator compiled in this expression.
+     */
     enum mtx_function_id function;
+
+    /**
+     * Vector of arguments.
+     */
     std::vector<MtxSymbol *> expressions;
+
+    /**
+     * True if silent.
+     * 
+     * A silent expression is an expression ended with the ';' character.
+     * Engine users should not display silent expressions. This property
+     * is propagated to underlying expressions and symbols.
+     * 
+     * @see isSilent()
+     */
     bool silent;
 
+    /**
+     * Find an operator in the vector of lexical elements.
+     * 
+     * This method uses the \a operators array to look for operators by
+     * order of precedence.
+     * 
+     * @param lexical_elements vector of strings in which to look for an
+     *                         operator
+     * @param str operator string as entered by the user to look for
+     * @see operators
+     * @see rfindOperator()
+     */
     mtx_expression_t::iterator
     findOperator(mtx_expression_t &lexical_elements, const char *str);
+
+    /**
+     * Find an operator in the vector of lexical elements in reverse order.
+     * 
+     * @see findOperator().
+     */
     mtx_expression_t::reverse_iterator
     rfindOperator(mtx_expression_t &lexical_elements, const char *str);
+
+    /**
+     * Free the pointers stored in the given vector of symbols.
+     * 
+     * Mainly used after parsing a matrix is done or failed.
+     */
     void freeMatrix(std::vector<MtxSymbol *> &symbols) const;
+
+    /**
+     * Parse the given lexical elements and extract symbols and expressions
+     * from it to create the list of elements that will be used to create a
+     * matrix. An exception is thrown if the syntax doesn't comply with
+     * the matrix creation syntax.
+     * 
+     * @param lexical_elements vector of strings to parse
+     * @param symbols vector of symbols/expressions updated by this method
+     * @param rows number of rows found
+     * @param columns number of columns found
+     */
     void parseMatrix(const mtx_expression_t &lexical_elements,
                      std::vector<MtxSymbol *> &symbols,
-                     size_t &rows, size_t &columns, bool silent) const;
+                     size_t &rows, size_t &columns) const;
 
 
-    /*
+    /**
+     * Multidimensional array of supported operators.
+     * 
+     * Each line of the array indicates a level of precedence. Lines must
+     * be ordered in reverse order of precedence, e.g. = has low precedence,
+     * so it is placed in first line. Operators of same precedence must have
+     * the same associativity (this is never checked).
+     * 
      * XXX There are at most 5 operators for the same precedence (+ a null
-     * entry to indicate end of list).
+     * entry to indicate end of list), so the second dimension is 6.
      */
     static struct mtx_operator operators[][6];
+
+    /**
+     * Return true if the given string matches an operator.
+     */
     static bool isOperator(const std::string &str);
 
   public:
+    /**
+     * Create an expression from a set of lexical elements.
+     * 
+     * @param language address of the MtxLanguage object used to get/set
+     *                 variables
+     * @param lexical_elements vector of lexical elements
+     * @param silent see silent
+     * @see silent
+     */
     MtxExpression(MtxLanguage *language, mtx_expression_t &lexical_elements,
-                  bool silent);
+                  bool silent = false);
+
     virtual ~MtxExpression();
     virtual MtxSymbol getSymbol(bool create = false,
                                 bool fail_if_special = true) const;
     virtual std::string getName() const;
     virtual MtxValue * getValue() const;
     virtual std::string toString() const;
+
+    /**
+     * Return the silent member.
+     * 
+     * As MtxExpression objects are always nodes, and there is always a node
+     * on top of a leaf, it is not necessary to propagate the silent property
+     * to underlying objects. When the engine calls isSilent(), it always get
+     * a return value from the first node it is calling the function on.
+     * That's why MtxSymbol objects don't have a silent property.
+     */
     virtual bool isSilent() const;
 };
 
diff --git a/mtxhistory.h b/mtxhistory.h
index e3d3abc..ee2e2d7 100644
--- a/mtxhistory.h
+++ b/mtxhistory.h
@@ -24,17 +24,56 @@
 #include <string>
 #include <vector>
 
+/**
+ * Object implementing history support.
+ * 
+ * Mainly used for command line history.
+ */
 class MtxHistory
 {
   private:
+    /**
+     * Vector of strings handled.
+     */
     std::vector<std::string> strings;
+
+    /**
+     * Iterator pointing to the current string.
+     */
     std::vector<std::string>::iterator offset;
 
   public:
+    /**
+     * Default constructor.
+     */
     MtxHistory();
+
+    /**
+     * Add a string at the end of the vector of strings.
+     * 
+     * The offset is automatically set to this string.
+     */
     void addString(const std::string &string);
+
+    /**
+     * Return string at current offset.
+     * 
+     * Return an empty string if offset points at the end of the vector.
+     */
     std::string getString() const;
+
+    /**
+     * Decrement offset.
+     * 
+     * If offset is already set to the first string, nothing is done.
+     */
     void previousString();
+
+    /**
+     * Increment offset.
+     * 
+     * If offset is already set to the end of the vector, nothing is done.
+     */
     void nextString();
 };
 
diff --git a/mtxlanguage.cc b/mtxlanguage.cc
index fbaf6b8..623db7c 100644
--- a/mtxlanguage.cc
+++ b/mtxlanguage.cc
@@ -201,7 +201,7 @@ MtxLanguage::parseExpressions(const mtx_expression_t &lexical_elements)
           if (!tmp.empty())
             {
               if (*iterator == ",")
-                expressions.push_back(new MtxExpression(this, tmp, false));
+                expressions.push_back(new MtxExpression(this, tmp));
 
               else if (*iterator == ";")
                 expressions.push_back(new MtxExpression(this, tmp, true));
@@ -245,7 +245,7 @@ MtxLanguage::parseExpressions(const mtx_expression_t &lexical_elements)
     throw MtxException("syntax error, missing ]");
 
   if (!tmp.empty())
-    expressions.push_back(new MtxExpression(this, tmp, false));
+    expressions.push_back(new MtxExpression(this, tmp));
 
   return expressions;
 }
diff --git a/mtxlanguage.h b/mtxlanguage.h
index 78eebf0..d95b20a 100644
--- a/mtxlanguage.h
+++ b/mtxlanguage.h
@@ -27,57 +27,116 @@
 #include "mtx.h"
 #include "mtxsymbol.h"
 
+/**
+ * \def MTXLANGUAGE_VALUES_INDEX
+ * \brief Index of the lexical group of values in lexical groups array.
+ */
 #define MTXLANGUAGE_VALUES_INDEX 0
+
+/**
+ * \def MTXLANGUAGE_OPERATORS_INDEX
+ * \brief Index of the lexical group of operators in lexical groups array.
+ */
 #define MTXLANGUAGE_OPERATORS_INDEX 1
+
+/**
+ * \def MTXLANGUAGE_OPERATORS_MAX_LENGTH
+ * \brief Maximum length of the string representation of an operator.
+ */
 #define MTXLANGUAGE_OPERATORS_MAX_LENGTH 2
+
+/**
+ * \def MTXLANGUAGE_ANS_VARIABLE
+ * \brief name of the automatic variable \a ans
+ */
 #define MTXLANGUAGE_ANS_VARIABLE "ans"
 
+/**
+ * Main language object used as interface between user and engine.
+ */
 class MtxLanguage
 {
   private:
+    /**
+     * Vector of known variables.
+     * 
+     * @see getSymbols()
+     */
     std::vector<MtxSymbol> symbols;
 
-    /*
-     * Return the lexical group of the character, or throw an exception if
-     * the character isn't registered.
+    /**
+     * Return the lexical group of the given character.
+     * 
+     * Throw an exception if the character isn't registered.
      */
     size_t findGroup(char c) const;
 
-    /*
+    /**
+     * Check a lexical element.
+     * 
      * Throw an exception if the lexical element is invalid.
      */
     void checkLexicalElement(const std::string &lexical_element) const;
 
-    /*
+    /**
+     * Lexical analysis.
+     * 
      * Return a vector of the lexical elements of the given expression. An
      * exception is thrown if an invalid character is present.
      */
     mtx_expression_t parseLexicalElements(const std::string &expression) const;
 
-    /*
+    /**
+     * Compile a set of lexical elements into expressions.
+     * 
      * Parse the given lexical elements and compile them in a vector of
-     * expressions. An exception is thrown if an error occurs.
+     * expressions. An MtxException exception is thrown if an error occurs.
      */
     std::vector<MtxSymbol *>
     parseExpressions(const mtx_expression_t &lexical_elements);
 
-    /*
+    /**
      * Release the memory referenced by the pointers in the given vector.
      */
     void freeExpressions(std::vector<MtxSymbol *> &expressions);
 
-    /*
-     * Array of groups of lexical elements, e.g. + and = are in the same
+    /**
+     * Array of groups of lexical elements. E.g. + and = are in the same
      * group.
      */
     static char *lexical_groups[];
-    static size_t operators_index;
 
   public:
+    /**
+     * Default constructor.
+     */
     MtxLanguage();
+
+    /**
+     * Parse the given expression into a set of results.
+     * 
+     * This is the main interface between the user and the engine.
+     * The caller should catch MtxException exceptions.
+     */
     std::vector<MtxSymbol> parse(const std::string &expression);
+
+    /**
+     * Set a named variable.
+     */
     void setSymbol(const MtxSymbol &symbol);
+
+    /**
+     * Get a variable from its name.
+     */
     MtxSymbol getSymbol(const std::string &name) const;
+
+    /**
+     * Return a copy of the vector of symbols.
+     * 
+     * Mainly used to list all registered variables.
+     * 
+     * @see symbols.
+     */
     std::vector<MtxSymbol> getSymbols() const;
 };
 
diff --git a/mtxmatrix.cc b/mtxmatrix.cc
index 32e6bef..ab23d69 100644
--- a/mtxmatrix.cc
+++ b/mtxmatrix.cc
@@ -431,7 +431,7 @@ MtxMatrix::l_inverted() const
   new_matrix = getIdentityMatrix(rows);
 
   /*
-   * Skip first line as we're working on a unit lower matrix.
+   * Skip first line as we're working on a unit lower triangular matrix.
    */
   for (i = 1; i < rows; i++)
     for (j = 0; j < i; j++)
diff --git a/mtxmatrix.h b/mtxmatrix.h
index 8f70bb2..e2f8c10 100644
--- a/mtxmatrix.h
+++ b/mtxmatrix.h
@@ -27,30 +27,157 @@
 #include "mtxvalue.h"
 #include "mtxrational.h"
 
+/**
+ * A matrix.
+ * 
+ * This class allows to create matrices which consist of an array of
+ * MtxRational objects, the number of rows, the number of columns, and
+ * the length of the array which is rows * columns.
+ */
 class MtxMatrix: public MtxValue
 {
   private:
+    /**
+     * Array of rationals.
+     */
     MtxRational *rationals;
+
+    /**
+     * The length of the array of rationals.
+     * 
+     * It is maintained internally to avoid computing rows * columns.
+     * 
+     * @see getLength()
+     */
     size_t length;
+
+    /**
+     * Number of rows.
+     * 
+     * @see getRows()
+     */
     size_t rows;
+
+    /**
+     * Number of columns.
+     * 
+     * @see getColumns()
+     */
     size_t columns;
 
+    /**
+     * Throw an MtxException exception if the rows of the current matrix and
+     * the rows of the given matrix differ.
+     * 
+     * This check if performed mainly before augmenting matrices.
+     * 
+     * @see checkDimensions()
+     */
     void checkRows(const MtxMatrix &matrix) const;
+
+    /**
+     * Check that both dimensions of the current matrix and the given matrix
+     * match.
+     * 
+     * A MtxException exception is thrown if one of the dimensions differ.
+     * Mainly used for addition like operations.
+     * 
+     * @see checkRows()
+     */
     void checkDimensions(const MtxMatrix &matrix) const;
+
+    /**
+     * Check compatibility of the current matrix with the given matrix.
+     * 
+     * Two matrices are compatible if the number of columns of the first
+     * is equal to the number of rows of the second. If matrices are not
+     * compatible, an MtxException exception is raised. Mainly used for
+     * matrix multiplication.
+     */
     void checkCompatibility(const MtxMatrix &matrix) const;
+
+    /**
+     * Check that the current matrix is a square matrix.
+     * 
+     * Throw an MtxException exception if the number of rows differs from
+     * the number of columns. Mainly used for LU decomposition.
+     */
     void checkSquare() const;
+
+    /**
+     * Add two rows.
+     * 
+     * @param dst_row the index of the row which is updated
+     * @param src_row the index of the row which is added to dst_row
+     * @param rational a coefficient which is applied to each element of
+     *                 src_row before addition
+     */
     void addRows(size_t dst_row, size_t src_row, const MtxRational &rational);
+
+    /**
+     * Subtract two rows.
+     * 
+     * @param dst_row the index of the row which is updated
+     * @param src_row the index of the row which is subtracted from dst_row
+     * @param rational a coefficient which is applied to each element of
+     *                 src_row before subtraction
+     */
     void subtractRows(size_t dst_row, size_t src_row,
                       const MtxRational &rational);
+
+    /**
+     * Multiply a row by a rational.
+     * 
+     * @param row the index of the row which is updated
+     * @param rational a coefficient which is applied to each element of
+     *                 row
+     */
     void multiplyRow(size_t row, const MtxRational &rational);
+
+    /**
+     * Divide a row by a rational.
+     * 
+     * @param row the index of the row which is updated
+     * @param rational a coefficient which inverse is applied to each element
+     *                 of row
+     */
     void divideRow(size_t row, const MtxRational &rational);
+
+    /**
+     * Switch two rows.
+     * 
+     * @param r1 the index of the first row
+     * @param r2 the index of the second row
+     */
     void switchRows(size_t r1, size_t r2);
+
+    /**
+     * Inverse the current matrix if this matrix is a unit lower triangular
+     * matrix.
+     * 
+     * Used for inversion of matrices.
+     */
     MtxMatrix l_inverted() const;
+
+    /**
+     * Inverse the current matrix if this matrix is an upper triangular matrix.
+     * 
+     * Used for inversion of matrices.
+     */
     MtxMatrix u_inverted() const;
 
   public:
+    /**
+     * Default constructor.
+     */
     MtxMatrix();
+
+    /**
+     * Create a matrix from an array of rationals, the number of rows and the
+     * number of columns. The caller must ensure coherent values are passed.
+     */
     MtxMatrix(MtxRational *rationals, size_t rows, size_t columns);
+
     MtxMatrix(const MtxMatrix &matrix);
     virtual ~MtxMatrix();
 
@@ -59,6 +186,14 @@ class MtxMatrix: public MtxValue
     /*
      * Some operators are available for easiness.
      */
+
+    /**
+     * Return the address of the line at requested index.
+     * 
+     * NULL is returned if index is invalid. Usage example :
+     * MtxRational r;
+     * r = matrix[1][2];
+     */
     MtxRational * operator[](size_t index) const;
     MtxMatrix operator+() const;
     MtxMatrix operator-() const;
@@ -80,36 +215,118 @@ class MtxMatrix: public MtxValue
     friend std::ostream & operator<<(std::ostream &cout,
                                      const MtxMatrix &matrix);
 
+    /**
+     * Return length.
+     * 
+     * @see length
+     */
     size_t getLength() const;
+
+    /**
+     * Return number of rows.
+     * 
+     * @see rows
+     */
     size_t getRows() const;
+
+    /**
+     * Return number of columns.
+     * 
+     * @see columns
+     */
     size_t getColumns() const;
+
+    /**
+     * Normalize each rational of the matrix.
+     */
     MtxMatrix & normalize();
+
+    /**
+     * Return the transpose of the matrix.
+     */
     MtxMatrix transpose() const;
+
+    /**
+     * Return the current matrix augmented with the given matrix.
+     */
     MtxMatrix augmented(const MtxMatrix &matrix) const;
+
+    /**
+     * Apply an LU decomposition.
+     * 
+     * @param L set to the unit lower triangular matrix
+     * @param U set to the upper triangular matrix
+     */
     void luDecomposition(MtxMatrix &L, MtxMatrix &U) const;
+
+    /**
+     * Return the determinant.
+     */
     MtxRational determinant() const;
+
+    /**
+     * Return the inverted matrix.
+     */
     MtxMatrix inverted() const;
 
-    /*
-     * Return a string representation of the matrix, in which values are
-     * aligned, seperated by white spaces, and framed with [()] characters.
+    /**
+     * Return a string representation of the matrix.
+     * 
+     * If float_string is true, matrix elements are returned in floating
+     * point representation, otherwise, they are returned in fractional
+     * representation.
+     * 
+     * @param float_string control rendering of the matrix elements
+     * @see toString()
+     * @see toFloatString()
      */
     std::string toString(bool float_string) const;
+
+    /**
+     * Return a string representation of the matrix.
+     * 
+     * Similar to toString(false).
+     * 
+     * @see toString(bool float_string) const
+     * @see toFloatString()
+     */
     virtual std::string toString() const;
+
+    /**
+     * Return a string representation of the matrix.
+     * 
+     * Similar to toString(true).
+     * 
+     * @see toString(bool float_string) const
+     * @see toString()
+     */
     std::string toFloatString() const;
 
     /*
      * See mtxvalue.h.
      */
     MTXVALUE_CLONE_METHOD_DECLARATION(MtxMatrix);
-
     virtual MtxValue * add(const MtxValue *value) const;
     virtual MtxValue * subtract(const MtxValue *value) const;
     virtual MtxValue * multiply(const MtxValue *value) const;
     virtual MtxValue * divide(const MtxValue *value) const;
     virtual MtxValue * opposite() const;
 
+    /**
+     * Return a zero matrix.
+     * 
+     * @param rows number of rows of the zero matrix
+     * @param columns number of columns of the zero matrix
+     */
     static MtxMatrix getZeroMatrix(size_t rows, size_t columns);
+
+    /**
+     * Return an identity matrix.
+     * 
+     * Note that an identity matrix is a square matrix.
+     * 
+     * @param n dimension of identity matrix
+     */
     static MtxMatrix getIdentityMatrix(size_t n);
 };
 
diff --git a/mtxsingularmatrixexception.h b/mtxsingularmatrixexception.h
index 64cf003..bc9df63 100644
--- a/mtxsingularmatrixexception.h
+++ b/mtxsingularmatrixexception.h
@@ -25,6 +25,12 @@
 
 #define MTX_SINGULARMATRIX_EXCEPTION_MESSAGE "matrix is singular"
 
+/**
+ * Singular matrix exception class.
+ * 
+ * This class exists so that singular matrix errors can be handled
+ * separately from other errors.
+ */
 class MtxSingularMatrixException: public MtxException
 {
   public:
diff --git a/mtxsymbol.h b/mtxsymbol.h
index 3178377..ab54b5e 100644
--- a/mtxsymbol.h
+++ b/mtxsymbol.h
@@ -28,61 +28,175 @@
 #include "mtxvalue.h"
 #include "mtxlanguage.h"
 
+/**
+ * A structure representing a special name.
+ * 
+ * Special names are e.g. "about" or "exit". They have a special meaning
+ * and are associated to a function. They should never be used as variable
+ * names or normal function names.
+ */
 struct mtx_special_name
 {
+  /**
+   * The special name.
+   */
   char *name;
+
+  /**
+   * Pointer to a function implementing the action associated to the special
+   * name.
+   */
   std::string (*function)(const MtxSymbol *);
 };
 
+/**
+ * A symbol.
+ * 
+ * Symbols are named or temporary values in the language engine.
+ * E.g. in the expression "a + 2", both \a a and \a 2 are symbols.
+ */
 class MtxSymbol
 {
   private:
+    /**
+     * Name of the symbol. An unnamed symbol is considered temporary.
+     */
     std::string name;
+
+    /**
+     * The value associated to the symbol.
+     */
     MtxValue *value;
+
+    /**
+     * If true, the symbol is special. I.e. it is created from a special name.
+     * When a special symbol is returned by the engine, the engine user should
+     * not display the "name = " string that usually prefixes the string
+     * representation of the value, so that the output of the commands
+     * associated to special names is unaltered when displayed.
+     * 
+     * @see setSpecial()
+     * @see isSpecial()
+     */
     bool special;
 
-    /*
-     * Set the member named special according to the value of the symbol name.
+    /**
+     * Set the special member according to the name of the symbol.
+     * 
+     * @see special
+     * @see isSpecial()
      */
     void setSpecial();
 
-    /*
+    /**
      * Return the index of the struct special_name entry which name matches
-     * the symbol name.
+     * the symbol name. The special member must be true, or this method will
+     * raise an MtxException exception.
      */
     size_t getSpecial() const;
 
-    /*
+    /**
      * List of special names and function pointers associated to them.
-     * Don't call it if special is false.
      */
     static struct mtx_special_name special_names[];
 
   protected:
-    /*
-     * This is the address of the MtxLanguage object used to retreive
-     * global symbols. The copy constructor and operator = must not
-     * duplicate the content of this pointer.
+    /**
+     * Address of the MtxLanguage object used to retreive global symbols.
+     * 
+     * The copy constructor and operator = must not duplicate the content
+     * of this pointer.
      */
     MtxLanguage *language;
 
   public:
+    /**
+     * Default constructor.
+     * 
+     * A symbol created with this constructor is unusable, as it doesn't
+     * have any link to an MtxLanguage object. The language object is needed
+     * to get and set named symbols from the global variable namespace of the
+     * language engine.
+     */
     MtxSymbol();
+
+    /**
+     * Create a named variable.
+     * 
+     * The value doesn't always need to be stored in the object itself, as
+     * it will be retreived from the MtxLanguage object.
+     */
     MtxSymbol(MtxLanguage *language, const std::string &name);
+
+    /**
+     * Create a temporary object.
+     */
     MtxSymbol(MtxLanguage *language, const MtxValue &value);
+
+    /**
+     * Create a named symbol with a value.
+     */
     MtxSymbol(MtxLanguage *language, const std::string &name,
               const MtxValue &value);
+
     MtxSymbol(const MtxSymbol &symbol);
     virtual ~MtxSymbol();
+
     MtxSymbol & operator=(const MtxSymbol &symbol);
+
+    /**
+     * Return a copy of the symbol.
+     * 
+     * This method is actually where execution takes place.
+     * 
+     * @param create if the symbol is a nonexistent named variable, create it
+     * @param fail_if_special if the symbol is special, raise an exception
+     */
     virtual MtxSymbol getSymbol(bool create = false,
                                 bool fail_if_special = true) const;
+
+    /**
+     * Return the name of the symbol.
+     */
     virtual std::string getName() const;
+
+    /**
+     * Set the name of the symbol. The symbol becomes a named variable if it
+     * was unnamed. It will be registered in the MtxLanguage object when
+     * getSymbol() is called.
+     */
     void setName(const std::string &name);
+
+    /**
+     * Return the address of the underlying value associated to the symbol.
+     * 
+     * This address can be NULL if no value was associated.
+     */
     virtual MtxValue * getValue() const;
+
+    /**
+     * Return the string representation of the underlying value.
+     */
     virtual std::string toString() const;
+
+    /**
+     * This method should never be used on a MtxSymbol object.
+     * 
+     * @see MtxExpression
+     */
     virtual bool isSilent() const;
+
+    /**
+     * Return the special member.
+     * 
+     * @see special
+     * @see setSpecial()
+     */
     bool isSpecial() const;
+
+    /**
+     * Return the address of the associated MtxLanguage object.
+     */
     MtxLanguage * getLanguage() const;
 };
 
diff --git a/mtxvalue.h b/mtxvalue.h
index e5b3e8a..a4e297d 100644
--- a/mtxvalue.h
+++ b/mtxvalue.h
@@ -23,12 +23,16 @@
 
 #include <string>
 
-/*
- * These two macros allow easy implementation of the clone() method of
- * derived classes.
+/**
+ * \def MTXVALUE_CLONE_METHOD_DECLARATION
+ * \brief Allows easy decleration of clone() method in derived classes.
  */
 #define MTXVALUE_CLONE_METHOD_DECLARATION(type) virtual type * clone() const
 
+/**
+ * \def MTXVALUE_CLONE_METHOD
+ * \brief Allows easy implementation of clone() method in derived classes.
+ */
 #define MTXVALUE_CLONE_METHOD(type) \
 type * \
 type::clone() const \
@@ -39,21 +43,52 @@ type::clone() const \
   return new_object; \
 }
 
+/**
+ * Abstract class for values used by the engine.
+ */
 class MtxValue
 {
   public:
     virtual ~MtxValue();
+
+    /**
+     * Return a string representation of the value.
+     */
     virtual std::string toString() const = 0;
 
-    /*
-     * Create a copy of the derived object and return its address.
+    /**
+     * Create a copy of the object and return its address.
      */
     virtual MtxValue * clone() const = 0;
 
+    /**
+     * Add the current value with the given value and return the address of
+     * the result. This result must be deleted by the caller.
+     */
     virtual MtxValue * add(const MtxValue *value) const = 0;
+
+    /**
+     * Subtract the given value from the current value and return the address
+     * of the result. This result must be deleted by the caller.
+     */
     virtual MtxValue * subtract(const MtxValue *value) const = 0;
+
+    /**
+     * Multiply the current value by the given value and return the address
+     * of the result. This result must be deleted by the caller.
+     */
     virtual MtxValue * multiply(const MtxValue *value) const = 0;
+
+    /**
+     * Divide the current value by the given value and return the address
+     * of the result. This result must be deleted by the caller.
+     */
     virtual MtxValue * divide(const MtxValue *value) const = 0;
+
+    /**
+     * Return a pointer to the opposite of the value.
+     * This pointer must be deleted by the caller.
+     */
     virtual MtxValue * opposite() const = 0;
 };
 
diff --git a/mtxwindow.h b/mtxwindow.h
index 1dcb8f1..b689f41 100644
--- a/mtxwindow.h
+++ b/mtxwindow.h
@@ -30,6 +30,9 @@
 
 #define MTXWINDOW_PROMPT ">> "
 
+/**
+ * Main GUI object.
+ */
 class MtxWindow: public Gtk::Window
 {
   private:
@@ -41,7 +44,15 @@ class MtxWindow: public Gtk::Window
     Glib::RefPtr<Gtk::TextBuffer> buffer;
     Glib::RefPtr<Gtk::TextBuffer::Tag> tag;
     Glib::RefPtr<Gtk::TextBuffer::Mark> mark;
+
+    /**
+     * Single line input box, used to get commands from user.
+     */
     MtxEntry entry;
+
+    /**
+     * Pointer to the MtxLanguage object, used to get/set variables.
+     */
     MtxLanguage *language;
 
     void on_menu_help_about();
@@ -49,6 +60,10 @@ class MtxWindow: public Gtk::Window
   public:
     MtxWindow(MtxLanguage *language);
     virtual ~MtxWindow();
+
+    /**
+     * Add the given text to the text view of the window.
+     */
     void addText(const std::string &text);
 };