add more comments

1 files changed, 36 insertions, 10 deletions

diff --git a/lua.go b/lua.go
index e7eee54..d7f27fa 100644
--- a/lua.go
+++ b/lua.go
@@ -27,25 +27,30 @@ import (
 )
 
 type LuaRef C.longlong
+// Lua is a wrapper around C Lua state with several conveniences.
 type Lua struct {
 	l *C.lua_State
 }
 
 //export luna_run_go_func
+// luna_run_go_func calls a Go function from C/Lua.
 func luna_run_go_func(f C.uintptr_t) C.int {
 	fn := cgo.Handle(f).Value().(func() int)
 	return C.int(fn())
 }
 
+// Start opens the Lua context with all built-in libraries.
 func (l *Lua) Start() {
 	l.l = C.luaL_newstate()
 	C.luaL_openlibs(l.l)
 }
 
+// Close closes the Lua context.
 func (l *Lua) Close() {
 	C.lua_close(l.l)
 }
 
+// Require loads and executes the file pushing results onto the Lua stack.
 func (l *Lua) Require(file string) error {
 	if !l.LoadFile(file) {
 		errMsg := l.ToString(-1)
@@ -59,7 +64,8 @@ func (l *Lua) Require(file string) error {
 	return nil
 }
 
-
+// PCall calls a function with the stack index (-nargs - 1) expecting nresults
+// number of results.
 func (l *Lua) PCall(nargs int, nresults int) error {
 	res := C.lua_pcallk(l.l, C.int(nargs), C.int(nresults), 0, 0, nil)
 	if res != C.LUA_OK {
@@ -70,6 +76,7 @@ func (l *Lua) PCall(nargs int, nresults int) error {
 	return nil
 }
 
+// LoadFile loads the file code in the current Lua context.
 func (l *Lua) LoadFile(file string) bool {
 	cstr := C.CString(file)
 	defer C.free(unsafe.Pointer(cstr))
@@ -77,41 +84,52 @@ func (l *Lua) LoadFile(file string) bool {
 	return res == C.LUA_OK
 }
 
+// StackLen returns the length of the Lua stack.
 func (l *Lua) StackLen() int {
 	return int(C.lua_gettop(l.l))
 }
 
+// ToInt converts a stack value with stack index -1 into a string.
 func (l *Lua) ToString(index int) string {
 	return C.GoString(C.lua_tolstring(l.l, C.int(index), nil))
 }
 
+// ToInt converts a stack value with stack index -1 into a number.
 func (l *Lua) ToInt(index int) int {
 	return int(C.lua_tonumberx(l.l, C.int(index), nil))
 }
 
+// PopToRef pops the item (stack offset -1) from the stack and then stores it
+// in the registry.
 func (l *Lua) PopToRef() LuaRef {
 	return LuaRef(C.luaL_ref(l.l, C.LUA_REGISTRYINDEX))
 }
 
+// Pop pops N items from the Lua stack.
 func (l *Lua) Pop(n int) {
 	C.lua_settop(l.l, C.int(-n - 1))
 }
 
+// PushNumber pushes tnil onto the Lua stack.
 func (l *Lua) PushNil() {
 	C.lua_pushnil(l.l)
 }
 
+// PushNumber pushes the number onto the Lua stack.
 func (l *Lua) PushNumber(num int) {
 	C.lua_pushnumber(l.l, C.double(num))
 }
 
+// PushString pushes the string onto the Lua stack.
 func (l *Lua) PushString(str string) {
 	cstr := C.CString(str)
 	defer C.free(unsafe.Pointer(cstr))
 	C.lua_pushstring(l.l, cstr)
 }
 
-// You may need to delete handle with .Delete() method later.
+// PushGoFunction pushes a Go function onto the Lua stack so it's possible to
+// call it from Lua. You may need to delete returned handle with .Delete()
+// method later.
 func (l *Lua) PushGoFunction(f func (l *Lua) int) cgo.Handle {
 	h := cgo.NewHandle(func () int {
 		return f(l)
@@ -120,17 +138,20 @@ func (l *Lua) PushGoFunction(f func (l *Lua) int) cgo.Handle {
 	return h
 }
 
-// CreateTable pushes a new table onto the stack.
+// CreateTable pushes a new Lua table onto the stack.
 func (l *Lua) CreateTable(len int) {
 	C.lua_createtable(l.l, 0, C.int(len))
 }
 
+// SetTableItem adds a value (stack offset -1) to a table (offset -2) under
+// the specified key.
 func (l *Lua) SetTableItem(key string) {
 	cstr := C.CString(key)
 	defer C.free(unsafe.Pointer(cstr))
 	C.lua_setfield(l.l, -2, C.CString(key))
 }
 
+// PushStringTable pushes string->string table onto the stack.
 func (l *Lua) PushStringTable(table map[string]string) {
 	l.CreateTable(len(table))
 	for k, v := range table {
@@ -139,37 +160,38 @@ func (l *Lua) PushStringTable(table map[string]string) {
 	}
 }
 
+// PushFromRef pushes a value from registry ref onto the stack.
 func (l *Lua) PushFromRef(ref LuaRef) {
 	C.lua_rawgeti(l.l, C.LUA_REGISTRYINDEX, C.longlong(ref));
 }
 
-func (l *Lua) PushTableItem(key string) {
-	ckey := C.CString(key)
-	defer C.free(unsafe.Pointer(ckey))
-	C.lua_pushstring(l.l, ckey);
-	C.lua_gettable(l.l, -2);
-}
-
+// IsString checks if the stack contains a string under the given index.
 func (l *Lua) IsString(index int) bool {
 	return C.lua_isstring(l.l, C.int(index)) == 1
 }
 
+// IsNumber checks if the stack contains a number (both int and float) under
+// the given index.
 func (l *Lua) IsNumber(index int) bool {
 	return C.lua_isnumber(l.l, C.int(index)) == 1
 }
 
+// IsFunction checks if the stack contains a function under the given index.
 func (l *Lua) IsFunction(index int) bool {
 	return C.lua_type(l.l, C.int(index)) == C.LUA_TFUNCTION
 }
 
+// IsTable checks if the stack contains a table under the given index.
 func (l *Lua) IsTable(index int) bool {
 	return C.lua_type(l.l, C.int(index)) == C.LUA_TTABLE
 }
 
+// Next advances a table iterator at the stack index -2.
 func (l *Lua) Next() bool {
 	return C.lua_next(l.l, -2) != 0
 }
 
+// LoadString loads and executes the code in the current Lua context.
 func (l *Lua) LoadString(code string) error {
 	cstr := C.CString(code)
 	defer C.free(unsafe.Pointer(cstr))
@@ -186,6 +208,8 @@ func (l *Lua) LoadString(code string) error {
 	return nil
 }
 
+// RestoreStackFunc remembers the Lua stack size and then restores it when a
+// returned function is called. It's a helper function to avoid stack leakage.
 func (l *Lua) RestoreStackFunc() func () {
 	before := l.StackLen()
 	return func () {
@@ -205,12 +229,14 @@ func (l *Lua) RestoreStackFunc() func () {
 	}
 }
 
+// SetGlobal sets a global value at the -1 stack index with the name.
 func (l *Lua) SetGlobal(name string) {
 	cstr := C.CString(name)
 	defer C.free(unsafe.Pointer(cstr))
 	C.lua_setglobal(l.l, cstr)
 }
 
+// GetGlobal gets a global value under the name.
 func (l *Lua) GetGlobal(name string) {
 	cstr := C.CString(name)
 	defer C.free(unsafe.Pointer(cstr))