writing documents

docs/api_reference/index.rst

@@ -5,5 +5,8 @@ API Reference
 .. toctree::
    :maxdepth: 2
 
+   preprocessor_option
    state
+   metatable
    luaref
+   standard

docs/api_reference/luaref.rst

@@ -2,8 +2,8 @@
 LuaRef
 ==================================
 
-LuaRef is referenceto lua value.
-and retain reference count in Lua.It means not collect by gc.
+LuaRef has strong reference to lua value.
+It means not collect by gc.
 
 
 LuaRef has specialized 4 types.
@@ -26,7 +26,7 @@ example
   state.dostring("mytable.value = 6");//assign new value
   state.dostring("mytable=nil");//remove from global table
   state.dostring("collectgarbage()");//run fullgc
-  v = table["value"];//v is 6. 
+  v = table["value"];//v is 6.
 
 .. toctree::
   :maxdepth: 1

docs/api_reference/metatable.rst

@@ -0,0 +1,7 @@
+
+UserdataMetatable
+========================
+
+
+.. doxygenclass:: kaguya::UserdataMetatable
+  :members:

docs/api_reference/preprocessor_option.rst

@@ -0,0 +1,67 @@
+
+Preprocessor Options
+==================================
+
+This option must be same between translation units.
+
+.. _preprocessor-use-cpp11:
+* KAGUYA_USE_CPP11
+
+  | If defined 1, kaguya use C++11 feature.
+  | If defined 0, kaguya use C++03 only (need boost library).
+  | default is auto detect (using _MSC_VER or __cplusplus).
+
+|
+
+* KAGUYA_NO_USERDATA_TYPE_CHECK
+
+  If defined 1, Skip type check for userdata created without kaguya.
+
+  .. warning::
+
+    This option is dangerous to be used in conjunction with other Lua library.
+
+    example:
+
+     .. code-block:: lua
+
+       --io.stdin is created by lua standard libray.
+       kaguya_binded_receive_userdata_fn(io.stdin) -- Error not detected. this is undefined behavior.
+
+|
+
+* KAGUYA_NO_VECTOR_AND_MAP_TO_TABLE
+
+  If difined, std::map and std::vector will not be converted to a lua-table
+
+|
+
+* KAGUYA_NO_STD_VECTOR_TO_TABLE
+
+  If difined, std::vector will not be converted to a lua-table
+
+|
+
+* KAGUYA_NO_STD_MAP_TO_TABLE
+
+  If difined, std::map will not be converted to a lua-table
+
+|
+
+* KAGUYA_FUNCTION_MAX_ARGS
+
+  Define max argument count for binding function. default is 9.
+
+  .. note::
+
+    Effect in the C++03 only
+
+|
+
+* KAGUYA_FUNCTION_MAX_OVERLOADS
+
+  Define max overloads function count for binding functions. default is 9.
+
+  .. note::
+
+    Effect in the C++03 only

docs/api_reference/standard.rst

@@ -0,0 +1,35 @@
+
+kaguya::standard namespace
+==================================
+
+This namespace store standard libraries.
+
+using boost library for not enough in C++03.
+
+In this way it has been defined in kaguya/config.hpp
+
+.. code-block:: c++
+
+  namespace kaguya
+  {
+    namespace standard
+    {
+    #if KAGUYA_USE_CPP11
+      using namespace std;
+    #else
+      using namespace boost;
+    #endif
+    }
+  }
+
+
+Used switched types
+-----------------------------
+
+* tuple
+
+  using multiple return value.
+
+* shared_ptr
+
+  using shared_ptr assign. see :ref:`smartpointers<class-bindings-smartpointers>`.

docs/api_reference/state.rst

@@ -1,3 +1,7 @@
 
 State
 ==================================
+State is lua_State* wrapper class
+
+.. doxygenclass:: kaguya::State
+  :members:

docs/getting_started/class_bindings.rst

@@ -0,0 +1,99 @@
+
+Class Bindings
+==================================
+C++ classes binding use :doc:`/api_reference/metatable`.
+
+
+A quick example
+-------------------------
+
+Exposing classes to Lua
+
+.. code-block:: c++
+
+  //C++
+  struct MyClass
+  {
+      MyClass():x(0),y() {}
+      MyClass(int x,const std::string& y):x(x),y(y) {}
+      void setX(int v){x=v;}
+      int getX()const{return x;}
+      void setY(const char* v){y=v;}
+      const std::string& getY()const{return y;}
+  private:
+      int x;
+      std::string y;
+  };
+
+  ...
+  state["MyClass"] = kaguya::UserdataMetatable<MyClass>()
+    .setConstructors<MyClass(),MyClass(int,const std::string&)>()
+    .addFunction("setX", &MyClass::setX)
+    .addFunction("getX", &MyClass::getX)
+    .addProperty("y", &MyClass::getY, &MyClass::setY)
+    ;
+
+
+Usage in Lua
+
+.. code-block:: lua
+
+  local v = MyClass.new(4,'text')
+  print(v:getX()) -- output 4
+  print(v.y) -- output 'text'
+
+
+
+Object lifetime
+-------------------------
+
+Copy assign
+^^^^^^^^^^^^^^^^^^^^^^
+
+  Basic assign.
+  Copy object and managing lifetime by Lua.
+
+  example:
+
+  .. code-block:: c++
+
+    {
+      MyClass myobj;
+      state["a"] = myobj;
+    }
+    state.dostring("print(a.y)");//myobj is destroyed, but a is living.
+    state["a"] = 0;//override a.
+    state.gc().collect();  //copied object is garbage collected.
+
+Pointer assign
+^^^^^^^^^^^^^^^^^^^^^^
+
+  You need managing object lifetime by yourself.
+
+  broken code example:
+
+  .. code-block:: c++
+
+    MyClass* myptr = new MyClass();
+    state["a"] = myptr;
+    delete myptr;
+    state.dostring("print(a.y)")// a is destroyed. This is undefined behavior as dangling pointer.
+
+
+Smartpointers
+^^^^^^^^^^^^^^^^^^^^^^
+.. _class-bindings-smartpointers:
+
+  If you think troublesome for managing lifetime, can use shared_ptr.
+
+  .. code-block:: c++
+
+    kaguya::standard::shared_ptr<MyClass> mysptr = kaguya::standard::make_shared<MyClass>();
+    state["a"] = mysptr;
+    state.dostring("print(a.y)");
+
+  .. note::
+
+    If :ref:`KAGUYA_USE_CPP11<preprocessor-use-cpp11>` is 0,
+    std::shared_ptr(and std::tr1::shared_ptr) is unrecognized, and vice versa.
+    see :doc:`/api_reference/standard`

docs/getting_started/index.rst

@@ -7,3 +7,4 @@ Getting Started
 
    requirements
    tutorial
+   class_bindings

docs/getting_started/tutorial.rst

@@ -10,7 +10,7 @@ Installation
 ----------------------------------
 add "kaguya/include" directory to "header search path" of your project.
 
-Or generate single header file and copy to your project.
+Or generate single header file and add it to your project.
 
 .. code-block:: bash
 
@@ -142,28 +142,28 @@ basic
 
 .. code-block:: c++
 
-  int ret = state["math"]["abs"](-32);//call math.abs of Lua function
+  int ret = state["math"]["abs"](-32);
   assert(ret == 32);
 
 Specified result type
 
 .. code-block:: c++
 
-  auto ret = state["math"]["abs"].call<int>(-32);//call math.abs of Lua function
+  auto ret = state["math"]["abs"].call<int>(-32);
   assert(ret == 32);
 
 Optional result value
 
 .. code-block:: c++
 
-  kaguya::optional<int> ret = state["math"]["abs"](-32);//call math.abs of Lua function
+  kaguya::optional<int> ret = state["math"]["abs"](-32);
   assert(ret && *ret == 32);
 
 Multiple results
 
 .. code-block:: c++
 
-  state("multresfun =function() return 1,2,4 end");//registering multiple results function
+  state("multresfun =function() return 1,2,4 end");
   int a, b, c;
   kaguya::tie(a, b, c) = state["multresfun"]();
   std::cout << a << "," << b << "," << c << std::endl;//1,2,4

include/kaguya/metatable.hpp

@@ -178,6 +178,8 @@ namespace kaguya
 		}
 	}
 
+
+	/// class binding interface.
 	template<typename class_type, typename base_class_type = void>
 	class UserdataMetatable
 	{

include/kaguya/state.hpp

@@ -74,7 +74,7 @@ namespace kaguya
 		}
 	};
 
-	///@ lua_State wrap class
+	/// lua_State wrap class
 	class State
 	{
 		standard::shared_ptr<void> allocator_holder_;