Final documentation for release 3.0.0 completed

include/chaiscript/chaiscript.hpp

@@ -18,10 +18,32 @@
 ///
 /// The end user parts of the API are extremely simple both in size and ease of use.
 ///
-/// Currently, all source control and project management aspects of ChaiScript occur on <a href="http://www.github.com">github</a>.
+/// Currently, all source control and project management aspects of ChaiScript occur on <a href="http://www.github.comi/chaiscript">github</a>.
+///
+/// <hr>
+/// 
+/// \sa chaiscript
+/// \sa chaiscript::ChaiScript
+/// \sa \ref LangKeywordRef
+/// \sa \ref LangObjectSystemRef
+/// \sa http://www.chaiscript.com
+/// \sa http://www.github.com/ChaiScript/ChaiScript
+///
+/// <hr>
 ///
 /// \section gettingstarted Getting Started
 ///
+/// \li \ref basics
+/// \li \ref eval
+/// \li \ref addingitems
+/// \li \ref helpermacro
+/// \li \ref pointerconversions
+/// \li \ref baseclasses
+/// \li \ref functionobjects
+/// \li \ref threading
+/// \li \ref exceptions
+/// 
+/// 
 /// \subsection basics Basics
 /// 
 /// Basic simple example:
@@ -303,14 +325,68 @@
 /// 
 /// <hr>
 ///
-/// function objects
+/// \subsection functionobjects Function Objects
+///
+/// Functions are first class objects in Chaiscript and ChaiScript supports automatic conversion
+/// between ChaiScript functions and boost::function objects.
+///
+/// \code
+/// void callafunc(const boost::function<void (const std::string &)> &t_func)
+/// {
+///   t_func("bob");
+/// }
+/// 
+/// int main()
+/// {
+///   chaiscript::ChaiScript chai;
+///   chai.add(chaiscript::fun(&callafunc), "callafunc");
+///   chai("callafunc(fun(x) { print(x); })"); // pass a lambda function to the registered function
+///                                            // which expects a typed boost::function
+///
+///   boost::function<void ()> f = chai.eval<boost::function<void ()> >("dump_system");
+///   f(); // call the ChaiScript function dump_system, from C++
+/// }
+/// \endcode
 /// 
 /// <hr>
 ///
-/// \sa chaiscript
+/// \subsection threading Threading
-/// \sa chaiscript::ChaiScript
+/// 
-/// \sa http://www.chaiscript.com
+/// Thread safety is automatically handled within the ChaiScript system. Objects can be added
-/// \sa http://www.github.com/ChaiScript/ChaiScript
+/// and scripts executed from multiple threads. For each thread that executes scripts, a new
+/// context is created and managed by the engine.
+/// 
+/// Thread safety can be disabled by defining CHAISCRIPT_NO_THREADS when using the library.
+///
+/// Disabling thread safety increases performance and removes the requirement for boost_threads.
+///
+/// <hr>
+///
+/// \subsection exceptions Exception Handling
+/// 
+/// Exceptions can be thrown in ChaiScript and caught in C++ or thrown in C++ and caught in 
+/// ChaiScript.
+///
+/// \code
+/// void throwexception()
+/// {
+///   throw std::runtime_error("err");
+/// }
+/// 
+/// int main()
+/// {
+///   chaiscript::ChaiScript chai;
+///   chai.add(chaiscript::fun(&throwexception), "throwexception");
+///   chai("try { throwexception(); } catch (e) { print(e.what()); }"); // prints "err"
+/// 
+///   try {
+///     chai("throw(1)");
+///   } catch (chaiscript::Boxed_Value bv) {
+///     int i = chaiscript::boxed_cast<int>(bv);
+///     // i == 1
+///   }
+/// }
+/// \endcode
 
 /// \page LangObjectSystemRef ChaiScript Language Object Model Reference
 ///

releasenotes.txt

@@ -3,19 +3,19 @@ Changes since 2.3.3
 * Code simplifications
 * Fully integrate documentation with source code in doxygen style comments
 * Unit tests increased from 114 to 137
-* Automatic conversion between boost::function objects and ChaiScript functions ****
+* Automatic conversion between boost::function objects and ChaiScript functions 
 * Many bug fixes
 * Minor performance improvements
 * Namespace reorganization to make end user code more accessible
 * clang support
 * VisualStudio 2010 Support
-* Support for C++ base classes and automatic upcasting ****
+* Support for C++ base classes and automatic upcasting 
 * Remove __ reserved identifiers
 * Better code organization to reduce #ifdefs 
 * clanmills: command line options for chai eval
 * clanmills: parser cleanups and code reduction
-* Function introspection and reflection ****
+* Function introspection and reflection 
-* Correct function dispatch order to account for base classes and provide a defined order of dispatch ****
+* Correct function dispatch order to account for base classes and provide a defined order of dispatch 
 * Predictable object lifetime that emulates C++ stack lifetime
 * emarcotte: pkgconfig support
 * standardize on method/member naming and indentation
@@ -23,4 +23,4 @@ Changes since 2.3.3
 * Better support for const objects
 * Drastic reduction of runtime exceptions - making debug builds orders of magnitude faster
 * Support for platforms with no loadable module support
-* Add helper macro for registering class ****
+* Add helper macro for registering class