Documentation updates and namespace reorg for docs.

include/chaiscript/chaiscript.hpp

@@ -27,8 +27,10 @@
 
 
 /// \namespace chaiscript
-/// The chaiscript namespace contains every API call that the average user will be concerned with.
+/// \brief Every API call that the average user will be concerned with.
 
+/// \namespace chaiscript::detail
+/// \brief Classes and functions reserved for internal use. Items in this namespace are not supported.
 
 #include "dispatchkit/dispatchkit.hpp"
 #include "dispatchkit/bootstrap.hpp"

include/chaiscript/dispatchkit/bootstrap.hpp

@@ -16,6 +16,7 @@
 
 namespace chaiscript 
 {
+  /// \brief Classes and functions useful for bootstrapping of ChaiScript and adding of new types
   namespace bootstrap
   {
     namespace detail

include/chaiscript/dispatchkit/boxed_pod_value.hpp

@@ -16,11 +16,8 @@
 
 namespace chaiscript 
 {
-  
+ 
-  /**
+  /// \brief Represents any numeric type, generically. Used internally for generic operations between POD values
-   * Object which attempts to convert a Boxed_Value into a generic
-   * POD type and provide generic POD type operations
-   */
   class Boxed_POD_Value
   {
     public:

include/chaiscript/dispatchkit/boxed_value.hpp

@@ -23,12 +23,8 @@
 
 namespace chaiscript 
 {
-  /**
+  /// \brief A wrapper for holding any valid C++ type. All types in ChaiScript are Boxed_Value objects
-   * Boxed_Value is the main tool of the dispatchkit. It allows
+  /// \sa chaiscript::boxed_cast
-   * for boxed / untyped containment of any C++ object. It uses
-   * boost::any internally but also provides user access the underlying
-   * stored type information
-   */
   class Boxed_Value
   {
     public:

include/chaiscript/dispatchkit/dispatchkit.hpp

@@ -26,8 +26,14 @@
 #include "dynamic_object.hpp"
 #include "../chaiscript_threading.hpp"
 
+
+/// \namespace chaiscript::dispatch
+/// \brief Classes and functions specific to the runtime dispatch side of ChaiScript. Some items may be of use to the end user.
+
 namespace chaiscript
 {
+  /// \brief Holds a collection of ChaiScript settings which can be applied to the ChaiScript runtime.
+  ///        Used to implement loadable module support.
   class Module
   {
     public:
@@ -109,6 +115,7 @@ namespace chaiscript
         }
   };
 
+  /// Convenience typedef for Module objects to be added to the ChaiScript runtime
   typedef boost::shared_ptr<Module> ModulePtr;
 
   namespace detail

include/chaiscript/dispatchkit/type_info.hpp

@@ -31,9 +31,7 @@ namespace chaiscript
       };
   }
 
-  /**
+  /// \brief Compile time deduced information about a type
-   * compile time deduced information about a type
-   */
   class Type_Info
   {
     public:

include/chaiscript/language/chaiscript_common.hpp

@@ -14,9 +14,7 @@ namespace chaiscript
 {
   typedef ModulePtr (*Create_Module_Func)();
 
-  /**
+  /// Types of AST nodes available to the parser and eval
-   * Types of AST nodes available to the parser and eval
-   */
   class AST_Node_Type {
   public:
     enum Type { Error, Int, Float, Id, Char, Str, Eol, Fun_Call, Inplace_Fun_Call, Arg_List, Variable, Equation, Var_Decl,
@@ -43,9 +41,7 @@ namespace chaiscript
     }
   }
 
-  /**
+  /// \brief Convenience type for file positions
-   * Convenience type for file positions
-   */
   struct File_Position {
     int line;
     int column;
@@ -58,6 +54,8 @@ namespace chaiscript
 
   typedef boost::shared_ptr<struct AST_Node> AST_NodePtr;
 
+
+  /// \brief Classes which may be thrown during error cases when ChaiScript is executing.
   namespace exception
   {
     /**
@@ -99,9 +97,8 @@ namespace chaiscript
 
   }
 
-  /**
+ 
-   * The struct that doubles as both a parser ast_node and an AST node
+  /// \brief Struct that doubles as both a parser ast_node and an AST node.
-   */
   struct AST_Node : boost::enable_shared_from_this<AST_Node> {
     public:
       const std::string text;
@@ -171,50 +168,49 @@ namespace chaiscript
   };
 
 
-  
+  namespace eval
-
-
-  namespace detail
   {
-    /**
+    namespace detail
-     * Special type for returned values
-     */
-    struct Return_Value {
-      Boxed_Value retval;
-
-      Return_Value(const Boxed_Value &t_return_value) : retval(t_return_value) { }
-    };
-
-    /**
-     * Special type indicating a call to 'break'
-     */
-    struct Break_Loop {
-      Break_Loop() { }
-    };
-
-    /// Creates a new scope then pops it on destruction
-    struct Scope_Push_Pop
     {
-      Scope_Push_Pop(chaiscript::detail::Dispatch_Engine &t_de)
+      /**
-        : m_de(t_de)
+       * Special type for returned values
+       */
+      struct Return_Value {
+        Boxed_Value retval;
+
+        Return_Value(const Boxed_Value &t_return_value) : retval(t_return_value) { }
+      };
+
+      /**
+       * Special type indicating a call to 'break'
+       */
+      struct Break_Loop {
+        Break_Loop() { }
+      };
+
+      /// Creates a new scope then pops it on destruction
+      struct Scope_Push_Pop
       {
-        m_de.new_scope();
+        Scope_Push_Pop(chaiscript::detail::Dispatch_Engine &t_de)
-      }
+          : m_de(t_de)
+        {
+          m_de.new_scope();
+        }
 
-      ~Scope_Push_Pop()
+        ~Scope_Push_Pop()
-      {
+        {
-        m_de.pop_scope();
+          m_de.pop_scope();
-      }
+        }
 
 
-      private:
+        private:
         // explicitly unimplemented copy and assignment
         Scope_Push_Pop(const Scope_Push_Pop &);
         Scope_Push_Pop& operator=(const Scope_Push_Pop &);
 
         chaiscript::detail::Dispatch_Engine &m_de;
-    };
+      };
-
+    }
   }
 }
 

include/chaiscript/language/chaiscript_engine.hpp

@@ -219,6 +219,8 @@ namespace chaiscript
     typedef boost::shared_ptr<Loadable_Module> Loadable_Module_Ptr;
   }
 
+
+  /// \brief The main object that the ChaiScript user will use.
   class ChaiScript {
 
     mutable chaiscript::detail::threading::shared_mutex m_mutex;
@@ -248,7 +250,7 @@ namespace chaiscript
           return Boxed_Value();
         }
       }
-      catch (const detail::Return_Value &rv) {
+      catch (const chaiscript::eval::detail::Return_Value &rv) {
         return rv.retval;
       }
     }

include/chaiscript/language/chaiscript_eval.hpp

@@ -13,27 +13,29 @@
 
 namespace chaiscript
 {
-  /**
+  /// \brief Classes and functions that are part of the runtime eval system
-   * Helper function that will set up the scope around a function call, including handling the named function parameters
-   */
-  template <typename Eval_System>
-    const Boxed_Value eval_function (Eval_System &t_ss, const AST_NodePtr &t_node, const std::vector<std::string> &t_param_names, const std::vector<Boxed_Value> &t_vals) {
-      detail::Scope_Push_Pop spp(t_ss);
-
-      for (unsigned int i = 0; i < t_param_names.size(); ++i) {
-        t_ss.add_object(t_param_names[i], t_vals[i]);
-      }
-
-      try {
-        return t_node->eval(t_ss);
-      } catch (const detail::Return_Value &rv) {
-        return rv.retval;
-      } 
-    }
-
-
   namespace eval
   {
+    namespace detail
+    {
+      /**
+       * Helper function that will set up the scope around a function call, including handling the named function parameters
+       */
+      static const Boxed_Value eval_function(chaiscript::detail::Dispatch_Engine &t_ss, const AST_NodePtr &t_node, const std::vector<std::string> &t_param_names, const std::vector<Boxed_Value> &t_vals) {
+        chaiscript::eval::detail::Scope_Push_Pop spp(t_ss);
+
+        for (unsigned int i = 0; i < t_param_names.size(); ++i) {
+          t_ss.add_object(t_param_names[i], t_vals[i]);
+        }
+
+        try {
+          return t_node->eval(t_ss);
+        } catch (const detail::Return_Value &rv) {
+          return rv.retval;
+        } 
+      }
+    }
+
     struct Binary_Operator_AST_Node : public AST_Node {
       public:
         Binary_Operator_AST_Node(const std::string &t_ast_node_text = "", int t_id = AST_Node_Type::Bitwise_Xor, const boost::shared_ptr<std::string> &t_fname=boost::shared_ptr<std::string>(), int t_start_line = 0, int t_start_col = 0, int t_end_line = 0, int t_end_col = 0) :
@@ -101,7 +103,7 @@ namespace chaiscript
         Id_AST_Node(const std::string &t_ast_node_text = "", int t_id = AST_Node_Type::Id, const boost::shared_ptr<std::string> &t_fname=boost::shared_ptr<std::string>(), int t_start_line = 0, int t_start_col = 0, int t_end_line = 0, int t_end_col = 0) :
           AST_Node(t_ast_node_text, t_id, t_fname, t_start_line, t_start_col, t_end_line, t_end_col),
           m_value(get_value(t_ast_node_text))
-        { }
+      { }
 
         virtual ~Id_AST_Node() {}
         virtual Boxed_Value eval_internal(chaiscript::detail::Dispatch_Engine &t_ss) {
@@ -485,7 +487,7 @@ namespace chaiscript
           }
 
           return Boxed_Value(Proxy_Function(new dispatch::Dynamic_Proxy_Function
-                (boost::bind(&eval_function<chaiscript::detail::Dispatch_Engine>, boost::ref(t_ss), this->children.back(), t_param_names, _1),
+                (boost::bind(chaiscript::eval::detail::eval_function, boost::ref(t_ss), this->children.back(), t_param_names, _1),
                  static_cast<int>(numparams), this->children.back())));
         }
 
@@ -499,7 +501,7 @@ namespace chaiscript
         virtual Boxed_Value eval_internal(chaiscript::detail::Dispatch_Engine &t_ss){
           const size_t num_children = this->children.size();
 
-          detail::Scope_Push_Pop spp(t_ss);
+          chaiscript::eval::detail::Scope_Push_Pop spp(t_ss);
 
           for (size_t i = 0; i < num_children; ++i) {
             try {
@@ -510,7 +512,7 @@ namespace chaiscript
                 return retval;
               }
             }
-            catch (const chaiscript::detail::Return_Value &) {
+            catch (const chaiscript::eval::detail::Return_Value &) {
               throw;
             }
           }
@@ -552,19 +554,19 @@ namespace chaiscript
           boost::shared_ptr<dispatch::Dynamic_Proxy_Function> guard;
           if (guardnode) {
             guard = boost::shared_ptr<dispatch::Dynamic_Proxy_Function>
-              (new dispatch::Dynamic_Proxy_Function(boost::bind(&eval_function<chaiscript::detail::Dispatch_Engine>,
+              (new dispatch::Dynamic_Proxy_Function(boost::bind(chaiscript::eval::detail::eval_function,
-                                                      boost::ref(t_ss), guardnode,
+                                                                boost::ref(t_ss), guardnode,
-                                                      t_param_names, _1), static_cast<int>(numparams), guardnode));
+                                                                t_param_names, _1), static_cast<int>(numparams), guardnode));
           }
 
           try {
             const std::string & l_function_name = this->children[0]->text;
             const std::string & l_annotation = this->annotation?this->annotation->text:"";
             t_ss.add(Proxy_Function
-                (new dispatch::Dynamic_Proxy_Function(boost::bind(&eval_function<chaiscript::detail::Dispatch_Engine>,
+                (new dispatch::Dynamic_Proxy_Function(boost::bind(chaiscript::eval::detail::eval_function,
-                                                        boost::ref(t_ss), this->children.back(),
+                                                                  boost::ref(t_ss), this->children.back(),
-                                                        t_param_names, _1), static_cast<int>(numparams), this->children.back(),
+                                                                  t_param_names, _1), static_cast<int>(numparams), this->children.back(),
-                                            l_annotation, guard)), l_function_name);
+                                                      l_annotation, guard)), l_function_name);
           }
           catch (const exception::reserved_word_error &e) {
             throw exception::eval_error("Reserved word used as function name '" + e.word() + "'");
@@ -582,7 +584,7 @@ namespace chaiscript
         virtual Boxed_Value eval_internal(chaiscript::detail::Dispatch_Engine &t_ss) {
           bool cond;
 
-          detail::Scope_Push_Pop spp(t_ss);
+          chaiscript::eval::detail::Scope_Push_Pop spp(t_ss);
 
           try {
             cond = boxed_cast<bool>(this->children[0]->eval(t_ss));
@@ -607,7 +609,7 @@ namespace chaiscript
           }
           return Boxed_Value();
         }
-        
+
     };
 
     struct If_AST_Node : public AST_Node {
@@ -663,7 +665,7 @@ namespace chaiscript
         virtual Boxed_Value eval_internal(chaiscript::detail::Dispatch_Engine &t_ss){
           bool cond;
 
-          detail::Scope_Push_Pop spp(t_ss);
+          chaiscript::eval::detail::Scope_Push_Pop spp(t_ss);
 
           try {
             if (this->children.size() == 4) {
@@ -845,7 +847,7 @@ namespace chaiscript
         virtual Boxed_Value eval_internal(chaiscript::detail::Dispatch_Engine &t_ss){
           Boxed_Value retval;        
 
-          detail::Scope_Push_Pop spp(t_ss);
+          chaiscript::eval::detail::Scope_Push_Pop spp(t_ss);
 
           try {
             retval = this->children[0]->eval(t_ss);
@@ -1013,9 +1015,9 @@ namespace chaiscript
           boost::shared_ptr<dispatch::Dynamic_Proxy_Function> guard;
           if (guardnode) {
             guard = boost::shared_ptr<dispatch::Dynamic_Proxy_Function>
-              (new dispatch::Dynamic_Proxy_Function(boost::bind(&eval_function<chaiscript::detail::Dispatch_Engine>,
+              (new dispatch::Dynamic_Proxy_Function(boost::bind(chaiscript::eval::detail::eval_function,
-                                                      boost::ref(t_ss), guardnode,
+                                                                boost::ref(t_ss), guardnode,
-                                                      t_param_names, _1), static_cast<int>(numparams), guardnode));
+                                                                t_param_names, _1), static_cast<int>(numparams), guardnode));
           }
 
           try {
@@ -1025,10 +1027,10 @@ namespace chaiscript
             if (function_name == class_name) {
               t_ss.add(Proxy_Function
                   (new dispatch::detail::Dynamic_Object_Constructor(class_name, Proxy_Function
-                                                          (new dispatch::Dynamic_Proxy_Function(boost::bind(&eval_function<chaiscript::detail::Dispatch_Engine>,
+                                                                    (new dispatch::Dynamic_Proxy_Function(boost::bind(chaiscript::eval::detail::eval_function,
-                                                                                                  boost::ref(t_ss), this->children.back(),
+                                                                                                                      boost::ref(t_ss), this->children.back(),
-                                                                                                  t_param_names, _1), static_cast<int>(numparams), this->children.back(),
+                                                                                                                      t_param_names, _1), static_cast<int>(numparams), this->children.back(),
-                                                                                      l_annotation, guard)))), function_name);
+                                                                                                          l_annotation, guard)))), function_name);
 
             }
             else {
@@ -1040,10 +1042,10 @@ namespace chaiscript
               }
               t_ss.add(Proxy_Function
                   (new dispatch::detail::Dynamic_Object_Function(class_name, Proxy_Function
-                                                       (new dispatch::Dynamic_Proxy_Function(boost::bind(&eval_function<chaiscript::detail::Dispatch_Engine>,
+                                                                 (new dispatch::Dynamic_Proxy_Function(boost::bind(chaiscript::eval::detail::eval_function,
-                                                                                               boost::ref(t_ss), this->children.back(),
+                                                                                                                   boost::ref(t_ss), this->children.back(),
-                                                                                               t_param_names, _1), static_cast<int>(numparams), this->children.back(),
+                                                                                                                   t_param_names, _1), static_cast<int>(numparams), this->children.back(),
-                                                                                   l_annotation, guard)), ti)), function_name);
+                                                                                                       l_annotation, guard)), ti)), function_name);
 
             }
           }

include/chaiscript/language/chaiscript_parser.hpp

@@ -16,8 +16,10 @@
 
 namespace chaiscript
 {
+  /// \brief Classes and functions used during the parsing process.
   namespace parser
   {
+    /// \brief Classes and functions internal to the parsing process. Not supported for the end user.
     namespace detail 
     {
       enum Alphabet

include/chaiscript/utility/utility.hpp

@@ -55,6 +55,7 @@
 
 namespace chaiscript 
 {
+  /// \brief Classes and functions which provide general utility to the end user.
   namespace utility
   {
     inline std::string class_name_translator(const std::string &t_name)