Documentation updates.

include/chaiscript/dispatchkit/function_call.hpp

@@ -1,3 +1,9 @@
+// This file is distributed under the BSD License.
+// See LICENSE.TXT for details.
+// Copyright 2009, Jonathan Turner (jonathan.d.turner@gmail.com) 
+// and Jason Turner (lefticus@gmail.com)
+// http://www.chaiscript.com
+
 #include <boost/preprocessor.hpp>
 
 #define addparam(z,n,text)  params.push_back(Boxed_Value(BOOST_PP_CAT(p, n) ));
@@ -17,6 +23,10 @@
 
 namespace dispatchkit
 {
+  /**
+   * Internal helper class for handling the return
+   * value of a build_function_caller
+   */
   template<typename Ret>
     class Function_Caller_Ret
     {
@@ -32,6 +42,9 @@ namespace dispatchkit
         }
     };
 
+  /**
+   * Specialization for void return types
+   */
   template<>
     class Function_Caller_Ret<void>
     {
@@ -53,7 +66,15 @@ namespace dispatchkit
 #include BOOST_PP_ITERATE()
 
 namespace dispatchkit
-{ 
+{
+  /**
+   * Build a function caller that knows how to dispatch on a set of functions
+   * example: 
+   * boost::function<void (int)> f = 
+   *      build_function_caller(dispatchkit.get_function("print"));
+   * \returns A boost::function object for dispatching
+   * \param[in] funcs the set of functions to dispatch on.
+   */
   template<typename FunctionType>
     boost::function<FunctionType>
       build_function_caller(const std::vector<std::pair<std::string, boost::shared_ptr<Proxy_Function> > > &funcs)
@@ -62,6 +83,19 @@ namespace dispatchkit
         return build_function_caller_helper(p, funcs);
       }
 
+  /**
+   * Build a function caller for a particular Proxy_Function object
+   * useful in the case that a function is being pass out from scripting back
+   * into code
+   * example: 
+   * void my_function(boost::shared_ptr<Proxy_Function> f)
+   * {
+   *   boost::function<void (int)> local_f = 
+   *      build_function_caller(f);
+   * }
+   * \returns A boost::function object for dispatching
+   * \param[in] func A function to execute.
+   */
   template<typename FunctionType>
     boost::function<FunctionType>
       build_function_caller(boost::shared_ptr<Proxy_Function> func)
@@ -71,6 +105,10 @@ namespace dispatchkit
         return build_function_caller<FunctionType>(funcs);
       }
 
+  /**
+   * Helper for automatically unboxing a Boxed_Value that contains a function object
+   * and creating a typesafe C++ function caller from it.
+   */
   template<typename FunctionType>
     boost::function<FunctionType>
       build_function_caller(const Boxed_Value &bv)
@@ -78,7 +116,14 @@ namespace dispatchkit
         return build_function_caller<FunctionType>(boxed_cast<boost::shared_ptr<Proxy_Function> >(bv));
       }
 
-     
+  /**
+   * Helper for calling script code as if it were native C++ code
+   * example:
+   * boost::function<int (int, int)> f = build_functor(chai, "func(x, y){x+y}");
+   * \return a boost::function representing the passed in script
+   * \param[in] e ScriptEngine to build the script execution from
+   * \param[in] script Script code to build a function from
+   */
   template<typename FunctionType, typename ScriptEngine>
     boost::function<FunctionType> build_functor(ScriptEngine &e, const std::string &script)
     {
@@ -92,6 +137,9 @@ namespace dispatchkit
 
 namespace dispatchkit
 {
+  /**
+   * used internally for unwrapping a function call's types
+   */
   template<typename Ret BOOST_PP_COMMA_IF(n) BOOST_PP_ENUM_PARAMS(n, typename Param) >
     Ret function_caller(const std::vector<std::pair<std::string, boost::shared_ptr<Proxy_Function> > > &funcs 
         BOOST_PP_COMMA_IF(n) BOOST_PP_ENUM_BINARY_PARAMS(n, Param, p) )
@@ -103,6 +151,9 @@ namespace dispatchkit
       return Function_Caller_Ret<Ret>().call(funcs, params);
     }
 
+  /**
+   * used internally for unwrapping a function call's types
+   */
   template<typename Ret BOOST_PP_COMMA_IF(n) BOOST_PP_ENUM_PARAMS(n, typename Param) >
     boost::function<Ret (BOOST_PP_ENUM_PARAMS(n, Param)) > 
       build_function_caller_helper(Ret (BOOST_PP_ENUM_PARAMS(n, Param)), const std::vector<std::pair<std::string, boost::shared_ptr<Proxy_Function> > > &funcs)