[gentoo-commits] proj/libbash:master commit in: src/, src/core/, src/builtins/

[Petteri Räty]

commit:     6c8652270b3f350b8621f2923d23f3f265146d59
Author:     Mu Qiao <qiaomuf <AT> gentoo <DOT> org>
AuthorDate: Sun Jul  3 08:49:10 2011 +0000
Commit:     Petteri Räty <betelgeuse <AT> gentoo <DOT> org>
CommitDate: Sun Jul  3 08:49:10 2011 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/libbash.git;a=commit;h=6c865227

Doc: improve documentation

Now make doxygen-doc doesn't show so many warnings. The documentation
for following things is not fixed: unit tests, private members, some
built-in constructors.

---
 src/builtins/boolean_builtins.h       |    2 +-
 src/builtins/builtin_exceptions.h     |    9 ++
 src/common.h                          |    2 +
 src/core/bash_ast.h                   |   55 +++++++++--
 src/core/bash_condition.h             |    8 ++
 src/core/divide_by_zero_error.h       |    2 +
 src/core/function.h                   |    9 ++-
 src/core/illegal_argument_exception.h |    2 +
 src/core/interpreter.h                |  166 ++++++++++++++++++--------------
 src/core/interpreter_exception.h      |    2 +
 src/core/parse_exception.h            |    2 +
 src/core/readonly_exception.h         |    2 +
 src/core/runtime_exception.h          |    2 +
 src/core/symbols.hpp                  |   34 ++++---
 src/core/unsupported_exception.h      |    2 +
 src/cppbash_builtin.h                 |   33 +++++--
 16 files changed, 223 insertions(+), 109 deletions(-)

diff --git a/src/builtins/boolean_builtins.h b/src/builtins/boolean_builtins.h
index fb7aca9..0d3db1a 100644
--- a/src/builtins/boolean_builtins.h
+++ b/src/builtins/boolean_builtins.h
@@ -17,7 +17,7 @@
    along with libbash.  If not, see <http://www.gnu.org/licenses/>.
 */
 ///
-/// \file boolean_builtins.cpp
+/// \file boolean_builtins.h
 /// \brief implementations for the true and false builtins
 ///
 #ifndef LIBBASH_BUILTINS_BOOLEAN_BUILTINS_H_

diff --git a/src/builtins/builtin_exceptions.h b/src/builtins/builtin_exceptions.h
index 7b45efc..e1a443a 100644
--- a/src/builtins/builtin_exceptions.h
+++ b/src/builtins/builtin_exceptions.h
@@ -49,8 +49,11 @@ protected:
   virtual ~loop_control_exception() {}
 
 public:
+  /// \brief the construtor
+  /// \param c the nested block counter
   explicit loop_control_exception(int c): count(c) {}
 
+  /// \brief rethrow the exception if the counter is greater than 1
   void rethrow_unless_correct_frame()
   {
     if(count != 1)
@@ -64,12 +67,15 @@ public:
 class continue_exception: public loop_control_exception
 {
 protected:
+  /// \brief rethrow the exception itself
   virtual void rethrow()
   {
     throw *this;
   }
 
 public:
+  /// \brief the constructor of the exception
+  /// \param c the nested block counter
   explicit continue_exception(int c): loop_control_exception(c) {
     if(c < 1)
       throw libbash::illegal_argument_exception("continue: argument should be greater than or equal to 1");
@@ -79,12 +85,15 @@ public:
 class break_exception: public loop_control_exception
 {
 protected:
+  /// \brief rethrow the exception itself
   virtual void rethrow()
   {
     throw *this;
   }
 
 public:
+  /// \brief the constructor of the exception
+  /// \param c the nested block counter
   explicit break_exception(int c): loop_control_exception(c) {
     if(c < 1)
       throw libbash::illegal_argument_exception("break: argument should be greater than or equal to 1");

diff --git a/src/common.h b/src/common.h
index 537e8d8..7203f02 100644
--- a/src/common.h
+++ b/src/common.h
@@ -24,7 +24,9 @@
 #ifndef LIBBASH_COMMON_H_
 #define LIBBASH_COMMON_H_
 
+/// compiler hint for public symbols
 #define LIBBASH_API __attribute__((visibility("default")))
+/// compiler hint for hidden symbols
 #define LIBBASH_LOCAL __attribute__((visibility("hidden")))
 
 #endif

diff --git a/src/core/bash_ast.h b/src/core/bash_ast.h
index 22635a1..fb42663 100644
--- a/src/core/bash_ast.h
+++ b/src/core/bash_ast.h
@@ -37,14 +37,19 @@
 struct libbashLexer_Ctx_struct;
 struct libbashParser_Ctx_struct;
 struct libbashWalker_Ctx_struct;
-typedef libbashWalker_Ctx_struct* plibbashWalker;
 class interpreter;
 
+/// \class bash_ast
+/// \brief customized unique_ptr for antlr objects.
 template<typename T>
 class antlr_pointer: public std::unique_ptr<T, std::function<void(T*)>>
 {
+  /// the constructor of base class
   typedef std::unique_ptr<T, std::function<void(T*)>> parent;
 public:
+  /// \brief constructor of antlr_pointer
+  /// \param p the pointer to the antlr objects, it should provide a method called 'free'
+  ///          to free the memory
   antlr_pointer(T* p = 0) : parent(p, [](T* to_delete) { to_delete->free(to_delete); }) {};
 };
 
@@ -61,54 +66,86 @@ class bash_ast: public boost::noncopyable
   antlr_pointer<ANTLR3_COMMON_TREE_NODE_STREAM_struct> nodes;
   std::function<pANTLR3_BASE_TREE(libbashParser_Ctx_struct*)> parse;
 
-  typedef std::unique_ptr<libbashWalker_Ctx_struct, std::function<void(plibbashWalker)>> walker_pointer;
+  typedef std::unique_ptr<libbashWalker_Ctx_struct, std::function<void(libbashWalker_Ctx_struct*)>> walker_pointer;
 
   void init_parser(const std::string& script, const std::string& script_path);
   walker_pointer create_walker(interpreter& walker);
 
 public:
+  /// \brief build AST from istream
+  /// \param source input source
+  /// \param p the parser rule for building the AST
   bash_ast(const std::istream& source,
            std::function<pANTLR3_BASE_TREE(libbashParser_Ctx_struct*)> p=parser_start);
 
+  /// \brief build AST from string
+  /// \param script_path input source
+  /// \param p the parser rule for building the AST
   bash_ast(const std::string& script_path,
            std::function<pANTLR3_BASE_TREE(libbashParser_Ctx_struct*)> p=parser_start);
 
-  static void walker_start(plibbashWalker tree_parser);
+  /// \brief the functor for walker start rule
+  /// \param tree_parser the pointer to the tree_parser
+  static void walker_start(libbashWalker_Ctx_struct* tree_parser);
 
-  static long walker_arithmetics(plibbashWalker tree_parser);
+  /// \brief the functor for walker arithmetics rule
+  /// \param tree_parser the pointer to the tree_parser
+  static long walker_arithmetics(libbashWalker_Ctx_struct* tree_parser);
 
-  static void call_function(plibbashWalker tree_parser,
+  /// \brief call a function that is defined in the AST
+  /// \param tree_parser the pointer to the tree_parser
+  /// \param index the function index
+  static void call_function(libbashWalker_Ctx_struct* tree_parser,
                             ANTLR3_MARKER index);
 
+  /// \brief the functor for parser start rule
+  /// \param parser the pointer to the parser
   static pANTLR3_BASE_TREE parser_start(libbashParser_Ctx_struct* parser);
 
+  /// \brief the functor for parser arithmetics rule
+  /// \param parser the pointer to the parser
   static pANTLR3_BASE_TREE parser_arithmetics(libbashParser_Ctx_struct* parser);
 
   ///
   /// \brief interpret the script with a given interpreter
-  /// \param the interpreter object
+  /// \param walker the interpreter object
+  /// \param walk the walker rule to evaluate the AST
   /// \return the interpreted result
   template<typename Functor>
-  typename std::result_of<Functor(plibbashWalker)>::type
+  typename std::result_of<Functor(libbashWalker_Ctx_struct*)>::type
   interpret_with(interpreter& walker, Functor walk)
   {
     walker_pointer p_tree_parser = create_walker(walker);
     return walk(p_tree_parser.get());
   }
 
+  ///
+  /// \brief use the start rule to interpret the script with a given interpreter
+  /// \param walker the interpreter object
   void interpret_with(interpreter& walker)
   {
     interpret_with(walker, walker_start);
   }
 
+  /// \brief get the dot graph for the AST
+  /// \return the dot graph
   std::string get_dot_graph();
 
+  /// \brief get the string tree for the AST
+  /// \return the string tree
   std::string get_string_tree();
 
+  /// \brief get parser tokens from a token stream
+  /// \param token_stream the token stream
+  /// \param token_mapper function that translates token numbers to token names
+  /// \return the parser tokens
   static std::string get_parser_tokens(antlr_pointer<ANTLR3_COMMON_TOKEN_STREAM_struct>& token_stream,
-                                       std::function<std::string(ANTLR3_UINT32)>);
+                                       std::function<std::string(ANTLR3_UINT32)> token_mapper);
 
-  std::string get_walker_tokens(std::function<std::string(ANTLR3_UINT32)>);
+  /// \brief get walker tokens from current AST
+  /// \param token_mapper function that translates token numbers to token names
+  /// \return the walker tokens
+  std::string get_walker_tokens(std::function<std::string(ANTLR3_UINT32)> token_mapper);
 };
 
 #endif

diff --git a/src/core/bash_condition.h b/src/core/bash_condition.h
index e8e4096..1c4f26c 100644
--- a/src/core/bash_condition.h
+++ b/src/core/bash_condition.h
@@ -29,8 +29,16 @@ class interpreter;
 
 namespace internal
 {
+  /// \brief implementation for built-in test unary operation
+  /// \param the operator
+  /// \param the operand
   bool test_unary(char op, const std::string& target);
 
+  /// \brief implementation for built-in test binary operation
+  /// \param the operator
+  /// \param the first operand
+  /// \param the second operand
+  /// \param a reference to the interpreter object
   bool test_binary(const std::string& op,
                    const std::string& lhs,
                    const std::string& rhs,

diff --git a/src/core/divide_by_zero_error.h b/src/core/divide_by_zero_error.h
index 10603cc..59e0fcb 100644
--- a/src/core/divide_by_zero_error.h
+++ b/src/core/divide_by_zero_error.h
@@ -39,6 +39,8 @@ namespace libbash
   class LIBBASH_API divide_by_zero_error: public libbash::interpreter_exception
   {
   public:
+    /// \brief the constructor
+    /// \param err_msg the error message
     explicit divide_by_zero_error(const std::string& err_msg):
       libbash::interpreter_exception(err_msg){}
   };

diff --git a/src/core/function.h b/src/core/function.h
index fcd0e91..92ae97c 100644
--- a/src/core/function.h
+++ b/src/core/function.h
@@ -17,7 +17,7 @@
    along with libbash.  If not, see <http://www.gnu.org/licenses/>.
 */
 ///
-/// \file function.hpp
+/// \file function.h
 /// \brief implementation for function
 ///
 
@@ -31,13 +31,20 @@
 class bash_ast;
 class interpreter;
 
+/// \class function
+/// \brief bash function implementation
 class function
 {
   bash_ast& ast;
   ANTLR3_MARKER index;
 public:
+  /// \brief the constructor
+  /// \param ast_ the reference to the AST
+  /// \param i the function index
   function(bash_ast& ast_, ANTLR3_MARKER i): ast(ast_), index(i){}
 
+  /// \brief call the function
+  /// \param walker the reference to the interpreter object
   void call(interpreter& walker);
 };
 

diff --git a/src/core/illegal_argument_exception.h b/src/core/illegal_argument_exception.h
index f67a9f6..847b6a8 100644
--- a/src/core/illegal_argument_exception.h
+++ b/src/core/illegal_argument_exception.h
@@ -39,6 +39,8 @@ namespace libbash
   class LIBBASH_API illegal_argument_exception: public libbash::interpreter_exception
   {
   public:
+    /// \brief the constructor
+    /// \param err_msg the error message
     explicit illegal_argument_exception(const std::string& err_msg):
       libbash::interpreter_exception(err_msg){}
   };

diff --git a/src/core/interpreter.h b/src/core/interpreter.h
index b0cfda5..c623e86 100644
--- a/src/core/interpreter.h
+++ b/src/core/interpreter.h
@@ -36,6 +36,7 @@
 #include "core/symbols.hpp"
 #include "cppbash_builtin.h"
 
+/// \brief symbol table implementation
 typedef std::unordered_map<std::string, std::shared_ptr<variable>> scope;
 
 ///
@@ -45,17 +46,14 @@ typedef std::unordered_map<std::string, std::shared_ptr<variable>> scope;
 class interpreter: public boost::noncopyable
 {
 
-  /// \var private::members
   /// \brief global symbol table for variables
   scope members;
 
-  /// \var private::function_definitions
   /// \brief global symbol table for functions
   std::unordered_map<std::string, function> functions;
 
   std::stack<bash_ast*> ast_stack;
 
-  /// \var private::local_members
   /// \brief local scope for function arguments, execution environment and
   ///        local variables
   std::vector<scope> local_members;
@@ -73,7 +71,6 @@ class interpreter: public boost::noncopyable
   // as bash implementation.
   std::map<char, bool> options;
 
-  /// \var private::status
   /// \brief the return status of the last command
   int status;
 
@@ -107,6 +104,7 @@ class interpreter: public boost::noncopyable
                            unsigned length) const;
 public:
 
+  /// bash option iterator
   typedef std::map<std::string, bool>::const_iterator option_iterator;
 
   ///
@@ -118,17 +116,21 @@ public:
     interpreter& walker;
 
   public:
+    /// \brief construtor
+    /// \param w the reference to the interpreter object
     local_scope(interpreter& w): walker(w)
     {
       walker.local_members.push_back(scope());
     }
 
+    /// \brief the destructor
     ~local_scope()
     {
       walker.local_members.pop_back();
     }
   };
 
+  /// \brief construtor
   interpreter();
 
   ///
@@ -174,11 +176,14 @@ public:
     return members.end();
   }
 
+  /// \brief set current output stream
+  /// \param stream the pointer to the output stream
   void set_output_stream(std::ostream* stream)
   {
     _out = stream;
   }
 
+  /// \brief restore the current output stream to standard output stream
   void restore_output_stream()
   {
     _out = &std::cout;
@@ -186,8 +191,8 @@ public:
 
   /// \brief resolve string/long variable, local scope will be
   ///        checked first, then global scope
-  /// \param variable name
-  /// \param array index, use index=0 if it's not an array
+  /// \param name variable name
+  /// \param index array index, use index=0 if it's not an array
   /// \return the value of the variable, call default constructor if
   ///         it's undefined
   template <typename T>
@@ -201,8 +206,8 @@ public:
   }
 
   /// \brief resolve array variable
-  /// \param variable name
-  /// \param[out] vector that stores all array values
+  /// \param name variable name
+  /// \param[out] values vector that stores all array values
   template <typename T>
   bool resolve_array(const std::string& name, std::vector<T>& values) const
   {
@@ -216,12 +221,13 @@ public:
 
   /// \brief check whether the value of the variable is null, return true
   ///        if the variable is undefined
-  /// \param variable name
+  /// \param name variable name
+  /// \param index array index, use index=0 if it's not an array
   /// \return whether the value of the variable is null
   bool is_unset_or_null(const std::string& name, const unsigned index) const;
 
   /// \brief check whether the value of the variable is unset
-  /// \param variable name
+  /// \param name variable name
   /// \return whether the value of the variable is unset
   bool is_unset(const std::string& name) const
   {
@@ -230,9 +236,9 @@ public:
 
   /// \brief update the variable value, raise libbash::interpreter_exception if
   ///        it's readonly, will define the variable if it doesn't exist
-  /// \param variable name
-  /// \param new value
-  /// \param array index, use index=0 if it's not an array
+  /// \param name variable name
+  /// \param new_value new value
+  /// \param index array index, use index=0 if it's not an array
   /// \return the new value of the variable
   template <typename T>
   const T& set_value(const std::string& name,
@@ -248,37 +254,36 @@ public:
   }
 
   /// \brief set the return status of the last command
-  /// \param the value of the return status
+  /// \param s the value of the return status
   void set_status(int s)
   {
     status = s;
   }
 
   /// \brief get the return status of the last command
-  /// \param the value of the return status
   int get_status(void) const
   {
     return status;
   }
 
   /// \brief unset a variable
-  /// \param the name of the variable
+  /// \param name the name of the variable
   void unset(const std::string& name);
 
   /// \brief unset a function
-  /// \param the name of the function
+  /// \param name the name of the function
   void unset_function(const std::string& name);
 
   /// \brief unset a array member
-  /// \param the name of the array
-  /// \param the index of the member
+  /// \param name the name of the array
+  /// \param index the index of the member
   void unset(const std::string& name, const unsigned index);
 
   /// \brief define a new global variable
-  /// \param the name of the variable
-  /// \param the value of the variable
-  /// \param whether it's readonly, default is false
-  /// \param whether it's null, default is false
+  /// \param name the name of the variable
+  /// \param value the value of the variable
+  /// \param readonly whether it's readonly, default is false
+  /// \param index whether it's null, default is false
   template <typename T>
   void define(const std::string& name,
               const T& value,
@@ -289,10 +294,10 @@ public:
   }
 
   /// \brief define a new local variable
-  /// \param the name of the variable
-  /// \param the value of the variable
-  /// \param whether it's readonly, default is false
-  /// \param whether it's null, default is false
+  /// \param name the name of the variable
+  /// \param value the value of the variable
+  /// \param readonly whether it's readonly, default is false
+  /// \param index whether it's null, default is false
   template <typename T>
   void define_local(const std::string& name,
                     const T& value,
@@ -303,8 +308,8 @@ public:
   }
 
   /// \brief define a new function
-  /// \param the name of the function
-  /// \param the body index of the function
+  /// \param name the name of the function
+  /// \param body_index the body index of the function
   void define_function(const std::string& name,
                        ANTLR3_MARKER body_index)
   {
@@ -312,7 +317,7 @@ public:
   }
 
   /// \brief push current AST, used for function definition
-  /// \param current ast
+  /// \param ast the pointer to the current ast
   void push_current_ast(bash_ast* ast)
   {
     ast_stack.push(ast);
@@ -325,24 +330,29 @@ public:
   }
 
   /// \brief make function call
-  /// \param function name
-  /// \param function arguments
+  /// \param name function name
+  /// \param arguments function arguments
   void call(const std::string& name,
             const std::vector<std::string>& arguments);
 
   /// \brief check if we have 'name' defined as a function
-  /// \param function name
+  /// \param name function name
   /// \return whether 'name' is a function
   bool has_function(const std::string& name) const
   {
     return functions.find(name) != functions.end();
   }
 
+  /// \brief get all defined function names
+  /// \param[out] function_names the place to store the function names
   void get_all_function_names(std::vector<std::string>& function_names) const;
 
   /// \brief execute builtin
-  /// \param builtin name
-  /// \param builtin arguments
+  /// \param name builtin name
+  /// \param args builtin arguments
+  /// \param output the output stream
+  /// \param error the error stream
+  /// \param input the input stream
   /// \return the return value of the builtin
   int execute_builtin(const std::string& name,
                       const std::vector<std::string>& args,
@@ -359,8 +369,9 @@ public:
   }
 
   /// \brief perform ${parameter:−word} expansion
-  /// \param the name of the parameter
-  /// \param the value of the word
+  /// \param name the name of the parameter
+  /// \param value the value of the word
+  /// \param index the index of the paramter
   /// \return the expansion result
   const std::string do_default_expansion(const std::string& name,
                                          const std::string& value,
@@ -371,8 +382,9 @@ public:
   }
 
   /// \brief perform ${parameter:=word} expansion
-  /// \param the name of the parameter
-  /// \param the value of the word
+  /// \param name the name of the parameter
+  /// \param value the value of the word
+  /// \param index the index of the paramter
   /// \return the expansion result
   const std::string do_assign_expansion(const std::string& name,
                                         const std::string& value,
@@ -383,8 +395,9 @@ public:
   }
 
   /// \brief perform ${parameter:+word} expansion
-  /// \param the name of the parameter
-  /// \param the value of the word
+  /// \param name the name of the parameter
+  /// \param value the value of the word
+  /// \param index the index of the paramter
   /// \return the expansion result
   const std::string do_alternate_expansion(const std::string& name,
                                            const std::string& value,
@@ -394,15 +407,19 @@ public:
   }
 
   /// \brief perform substring expansion
-  /// \param the offset of the substring
+  /// \param name the name of the parameter
+  /// \param offset the offset of the substring
+  /// \param index the index of the paramter
   /// \return the expansion result
   const std::string do_substring_expansion(const std::string& name,
                                            long long offset,
                                            const unsigned index) const;
 
   /// \brief perform substring expansion
-  /// \param the offset of the substring
-  /// \param the length of the substring
+  /// \param name the name of the parameter
+  /// \param offset the offset of the substring
+  /// \param length the length of the substring
+  /// \param index the index of the paramter
   /// \return the expansion result
   const std::string do_substring_expansion(const std::string& name,
                                            long long offset,
@@ -410,61 +427,64 @@ public:
                                            const unsigned index) const;
 
   /// \brief perform subarray expansion
-  /// \param the offset of the subarray
+  /// \param name the name of the parameter
+  /// \param offset the offset of the subarray
   /// \return the expansion result
   const std::string do_subarray_expansion(const std::string& name,
                                           long long offset) const;
 
   /// \brief perform subarray expansion
-  /// \param the offset of the subarray
-  /// \param the length of the subarray
+  /// \param name the name of the parameter
+  /// \param offset the offset of the subarray
+  /// \param length the length of the subarray
   /// \return the expansion result
   const std::string do_subarray_expansion(const std::string& name,
                                           long long offset,
                                           int length) const;
 
   /// \brief perform replacement expansion
-  /// \param the name of the varaible that needs to be expanded
-  /// \param the function object used to perform expansion
-  /// \param array index, use index=0 if it's not an array
+  /// \param name the name of the varaible that needs to be expanded
+  /// \param replacer the function object used to perform expansion
+  /// \param index array index, use index=0 if it's not an array
   /// \return the expanded value
   std::string do_replace_expansion(const std::string& name,
                                    std::function<void(std::string&)> replacer,
                                    const unsigned index) const;
 
   /// \brief get the length of a string variable
-  /// \param the name of the variable
+  /// \param name the name of the variable
+  /// \param index the index of the variable
   /// \return the length
   std::string::size_type get_length(const std::string& name, const unsigned index=0) const;
 
   /// \brief get the length of an array
-  /// \param the name of the array
+  /// \param name the name of the array
   /// \return the length of the array
   variable::size_type get_array_length(const std::string& name) const;
 
   /// \brief get all array elements concatenated by space
-  /// \param the name of the array
-  /// \param[out] the concatenated string
-  void get_all_elements(const std::string&, std::string&) const;
+  /// \param name the name of the array
+  /// \param[out] result the concatenated string
+  void get_all_elements(const std::string& name, std::string& result) const;
 
   /// \brief get all array elements concatenated by the first character of IFS
-  /// \param the name of the array
-  /// \param[out] the concatenated string
-  void get_all_elements_IFS_joined(const std::string&, std::string&) const;
+  /// \param name the name of the array
+  /// \param[out] result the concatenated string
+  void get_all_elements_IFS_joined(const std::string& name, std::string& result) const;
 
   /// \brief implementation of word splitting
-  /// \param the value of the word
-  //. \param[out] the splitted result will be appended to output
+  /// \param word the value of the word
+  //. \param[out] output the splitted result will be appended to output
   void split_word(const std::string& word, std::vector<std::string>& output) const;
 
   /// \brief get the status of shell optional behavior
-  /// \param the option name
+  /// \param name the option name
   /// \return zero unless the name is not a valid shell option
   bool get_additional_option(const std::string& name) const;
 
   /// \brief set the status of shell optional behavior
-  /// \param the option name
-  /// \param[in] true if option is enabled, false otherwise
+  /// \param name the option name
+  /// \param[in] value true if option is enabled, false otherwise
   /// \return zero unless the name is not a valid shell option
   void set_additional_option(const std::string& name, bool value);
 
@@ -484,34 +504,34 @@ public:
   }
 
   /// \brief evaluate arithmetic expression and return the result
-  /// \param the arithmetic expression
+  /// \param expression the arithmetic expression
   /// \return the evaluated result
   long eval_arithmetic(const std::string& expression);
 
   /// \brief perform expansion like ${var//foo/bar}
-  /// \param the value to be expanded
-  /// \param the pattern used to match the value
-  /// \param the replacement string
+  /// \param value the value to be expanded
+  /// \param pattern the pattern used to match the value
+  /// \param replacement the replacement string
   static void replace_all(std::string& value,
                           const boost::xpressive::sregex& pattern,
                           const std::string& replacement);
 
   /// \brief perform expansion like ${var%foo}
-  /// \param the value to be expanded
-  /// \param the pattern used to match the value
+  /// \param value the value to be expanded
+  /// \param pattern the pattern used to match the value
   static void lazy_remove_at_end(std::string& value,
                                  const boost::xpressive::sregex& pattern);
 
   /// \brief perform expansion like ${var/foo/bar}
-  /// \param the value to be expanded
-  /// \param the pattern used to match the value
-  /// \param the replacement string
+  /// \param value the value to be expanded
+  /// \param pattern the pattern used to match the value
+  /// \param replacement the replacement string
   static void replace_first(std::string& value,
                             const boost::xpressive::sregex& pattern,
                             const std::string& replacement);
 
   /// \brief remove trailing EOLs from the value
-  /// \param[in, out] the target
+  /// \param[in, out] value the target
   static void trim_trailing_eols(std::string& value);
 };
 #endif

diff --git a/src/core/interpreter_exception.h b/src/core/interpreter_exception.h
index ea5a9ef..11f909f 100644
--- a/src/core/interpreter_exception.h
+++ b/src/core/interpreter_exception.h
@@ -38,6 +38,8 @@ namespace libbash
   class LIBBASH_API interpreter_exception: public std::runtime_error
   {
   public:
+    /// \brief the constructor
+    /// \param err_msg the error message
     explicit interpreter_exception(const std::string& err_msg):
       runtime_error(err_msg){}
   };

diff --git a/src/core/parse_exception.h b/src/core/parse_exception.h
index 20860b4..6f19bff 100644
--- a/src/core/parse_exception.h
+++ b/src/core/parse_exception.h
@@ -39,6 +39,8 @@ namespace libbash
   class LIBBASH_API parse_exception: public libbash::interpreter_exception
   {
   public:
+    /// \brief the constructor
+    /// \param err_msg the error message
     explicit parse_exception(const std::string& err_msg):
       libbash::interpreter_exception(err_msg){}
   };

diff --git a/src/core/readonly_exception.h b/src/core/readonly_exception.h
index 97964de..16d1106 100644
--- a/src/core/readonly_exception.h
+++ b/src/core/readonly_exception.h
@@ -39,6 +39,8 @@ namespace libbash
   class LIBBASH_API readonly_exception: public libbash::interpreter_exception
   {
   public:
+    /// \brief the constructor
+    /// \param err_msg the error message
     explicit readonly_exception(const std::string& err_msg):
       libbash::interpreter_exception(err_msg){}
   };

diff --git a/src/core/runtime_exception.h b/src/core/runtime_exception.h
index da6fffa..ed87655 100644
--- a/src/core/runtime_exception.h
+++ b/src/core/runtime_exception.h
@@ -39,6 +39,8 @@ namespace libbash
   class LIBBASH_API runtime_exception: public libbash::interpreter_exception
   {
   public:
+    /// \brief the constructor
+    /// \param err_msg the error message
     explicit runtime_exception(const std::string& err_msg):
       libbash::interpreter_exception(err_msg){}
   };

diff --git a/src/core/symbols.hpp b/src/core/symbols.hpp
index 8c6dec7..c535f8f 100644
--- a/src/core/symbols.hpp
+++ b/src/core/symbols.hpp
@@ -53,7 +53,7 @@ class converter<long>: public boost::static_visitor<long>
 {
 public:
   /// \brief converter for long value
-  /// \param the value to be converted
+  /// \param value the value to be converted
   /// \return the converted long
   long operator() (const long value) const
   {
@@ -61,7 +61,7 @@ public:
   }
 
   /// \brief converter for string value
-  /// \param the value to be converted
+  /// \param value the value to be converted
   /// \return the converted long
   long operator() (const std::string& value) const
   {
@@ -88,7 +88,7 @@ class converter<std::string>:
 {
 public:
   /// \brief converter for long value
-  /// \param the value to be converted
+  /// \param value the value to be converted
   /// \return the converted string
   std::string operator() (const long value) const
   {
@@ -96,7 +96,7 @@ public:
   }
 
   /// \brief converter for string value
-  /// \param the value to be converted
+  /// \param value the value to be converted
   /// \return the converted string
   std::string operator() (const std::string& value) const
   {
@@ -110,21 +110,19 @@ public:
 ///
 class variable
 {
-  /// \var private::name
   /// \brief variable name
   std::string name;
 
-  /// \var private::value
   /// \brief actual value of the variable. We put string in front of long
   ///        because we want "" as default string value; Otherwise we
   ///        will get "0".
   std::map<unsigned, boost::variant<std::string, long>> value;
 
-  /// \var private::readonly
   /// \brief whether the variable is readonly
   bool readonly;
 
 public:
+  /// size_type for array length
   typedef std::map<unsigned, boost::variant<std::string, long>>::size_type size_type;
 
   /// \brief retrieve variable name
@@ -134,6 +132,11 @@ public:
     return name;
   }
 
+  /// \brief constructor
+  /// \param name the name of the variable
+  /// \param v the value of the variable
+  /// \param ro whether the variable is readonly
+  /// \param index the index of the variable, use 0 if it's not an array
   template <typename T>
   variable(const std::string& name,
            const T& v,
@@ -146,6 +149,7 @@ public:
 
   /// \brief retrieve actual value of the variable, if index is out of bound,
   ///        will return the default value of type T
+  /// \param index the index of the variable, use 0 if it's not an array
   /// \return the value of the variable
   template<typename T>
   T get_value(const unsigned index=0) const
@@ -160,7 +164,7 @@ public:
   }
 
   /// \brief retrieve all values of the array
-  /// \param[out] vector that stores all array values
+  /// \param[out] all_values vector that stores all array values
   template<typename T>
   void get_all_values(std::vector<T>& all_values) const
   {
@@ -173,9 +177,8 @@ public:
 
 
   /// \brief set the value of the variable, raise exception if it's readonly
-  /// \param the new value to be set
-  /// \param array index, use index=0 if it's not an array
-  /// \param whether to set the variable to null value, default is false
+  /// \param new_value the new value to be set
+  /// \param index array index, use index=0 if it's not an array
   template <typename T>
   void set_value(const T& new_value,
                  const unsigned index=0)
@@ -187,7 +190,7 @@ public:
   }
 
   /// \brief unset the variable, only used for array variable
-  /// \param the index to be unset
+  /// \param index the index to be unset
   void unset_value(const unsigned index)
   {
     if(readonly)
@@ -197,7 +200,7 @@ public:
   }
 
   /// \brief get the length of a variable
-  /// \param the index of the variable, use 0 if it's not an array
+  /// \param index the index of the variable, use 0 if it's not an array
   /// \return the length of the variable
   std::string::size_type get_length(const unsigned index=0) const
   {
@@ -233,7 +236,10 @@ public:
   }
 };
 
-// specialization for arrays
+/// \brief the specialized constructor for arrays
+/// \param name the variable name
+/// \param value the variable value
+/// \param ro whether the variable readonly
 template <>
 inline variable::variable<>(const std::string& name,
                             const std::map<unsigned, std::string>& v,

diff --git a/src/core/unsupported_exception.h b/src/core/unsupported_exception.h
index 338b087..9920a5c 100644
--- a/src/core/unsupported_exception.h
+++ b/src/core/unsupported_exception.h
@@ -39,6 +39,8 @@ namespace libbash
   class LIBBASH_API unsupported_exception: public libbash::interpreter_exception
   {
   public:
+    /// \brief the constructor
+    /// \param err_msg the error message
     explicit unsupported_exception(const std::string& err_msg):
       libbash::interpreter_exception(err_msg){}
   };

diff --git a/src/cppbash_builtin.h b/src/cppbash_builtin.h
index c42ee1a..04ff387 100644
--- a/src/cppbash_builtin.h
+++ b/src/cppbash_builtin.h
@@ -34,6 +34,7 @@
 #include <boost/scoped_ptr.hpp>
 #include <boost/utility.hpp>
 
+/// shortcut for the arguments of the constructor
 #define BUILTIN_ARGS std::ostream &out, std::ostream &err, std::istream &in, interpreter &walker
 
 class interpreter;
@@ -46,9 +47,10 @@ class cppbash_builtin: public boost::noncopyable
   public:
     ///
     /// \brief Default constructor, sets default streams
-    /// \param outstream where to send standard output.  Default: cout
-    /// \param errstream where to send standard error.  Default: cerr
-    /// \param instream where to get standard input from.  Default: stdin
+    /// \param out where to send standard output.  Default: cout
+    /// \param err where to send standard error.  Default: cerr
+    /// \param in where to get standard input from.  Default: stdin
+    /// \param walker the interpreter object
     ///
     explicit cppbash_builtin(BUILTIN_ARGS);
 
@@ -75,6 +77,14 @@ class cppbash_builtin: public boost::noncopyable
     ///
     std::istream& input_buffer() {return *_inp_stream;}
 
+    /// \brief execute the given builtin
+    /// \param builtin the builtin name
+    /// \param args the arguments
+    /// \param out where to send standard output.  Default: cout
+    /// \param err where to send standard error.  Default: cerr
+    /// \param in where to get standard input from.  Default: stdin
+    /// \param walker the interpreter object
+    /// \return the return status of the builtin
     static int exec(const std::string& builtin,
                     const std::vector<std::string>& args,
                     BUILTIN_ARGS)
@@ -85,8 +95,8 @@ class cppbash_builtin: public boost::noncopyable
 
     ///
     /// \brief check existence of the builtin
-    /// \param builtin name
-    /// \param whether it is a builtin
+    /// \param builtin builtin name
+    /// \return whether it is a builtin
     ///
     static bool is_builtin(const std::string& builtin)
     {
@@ -111,21 +121,22 @@ class cppbash_builtin: public boost::noncopyable
     ///
     std::istream *_inp_stream;
 
+    ///
+    /// \var _walker
+    /// \brief reference to the interpreter object
     interpreter& _walker;
 
-    ///
-    /// \var builtins
-    /// \brief holds factories for creating instances of child classes
-    ///
+    /// holds factories for creating instances of child classes
     typedef std::map<std::string, boost::function< cppbash_builtin*(BUILTIN_ARGS) >> builtins_type;
     static builtins_type& builtins();
 
     /// \brief transforms escapes in echo input
-    /// \param the target string
-    /// \param the place to write
+    /// \param string the target string
+    /// \param output the place to write
     void transform_escapes(const std::string &string, std::ostream& output) const;
 };
 
+/// shortcut for builtin constructor
 #define BUILTIN_CONSTRUCTOR(name) \
   name ## _builtin(BUILTIN_ARGS) : cppbash_builtin(out, err, in, walker) {}