Improve docs

Author: yuin

_vm.go

@@ -955,17 +955,6 @@ func equals(L *LState, lhs, rhs LValue, raw bool) bool {
 	return ret
 }
 
-func tostring(L *LState, lv LValue) LValue {
-	if fn, ok := L.metaOp1(lv, "__tostring").assertFunction(); ok {
-		L.Push(fn)
-		L.Push(lv)
-		L.Call(1, 1)
-		return L.reg.Pop()
-	} else {
-		return LString(lv.String())
-	}
-}
-
 func objectRationalWithError(L *LState, lhs, rhs LValue, event string) bool {
 	switch objectRational(L, lhs, rhs, event) {
 	case 1:

auxlib.go

@@ -398,6 +398,19 @@ func (ls *LState) OpenLibs() {
 
 /* GopherLua original APIs {{{ */
 
+// ToStringMeta returns string representation of given LValue.
+// This method calls the `__tostring` meta method if defined.
+func (ls *LState) ToStringMeta(lv LValue) LValue {
+	if fn, ok := ls.metaOp1(lv, "__tostring").assertFunction(); ok {
+		ls.Push(fn)
+		ls.Push(lv)
+		ls.Call(1, 1)
+		return ls.reg.Pop()
+	} else {
+		return LString(lv.String())
+	}
+}
+
 // Set a module loader to the package.preload table.
 func (ls *LState) PreloadModule(name string, loader LGFunction) {
 	preload := ls.GetField(ls.GetField(ls.Get(EnvironIndex), "package"), "preload")

baselib.go

@@ -268,7 +268,7 @@ func basePCall(L *LState) int {
 func basePrint(L *LState) int {
 	top := L.GetTop()
 	for i := 1; i <= top; i++ {
-		fmt.Print(tostring(L, L.Get(i)).String())
+		fmt.Print(L.ToStringMeta(L.Get(i)).String())
 		if i != top {
 			fmt.Print("\t")
 		}
@@ -409,7 +409,7 @@ func baseToNumber(L *LState) int {
 
 func baseToString(L *LState) int {
 	v1 := L.CheckAny(1)
-	L.Push(tostring(L, v1))
+	L.Push(L.ToStringMeta(v1))
 	return 1
 }
 

state.go

@@ -1,4 +1,4 @@
-// This file was generated by go-inline.DO NOT EDIT.
+// This file was generated by go-inline. DO NOT EDIT.
 package lua
 
 import (
@@ -758,7 +758,7 @@ func (ls *LState) pushCallFrame(cf callFrame, fn LValue, meta bool) { // +inline
 		ls.RaiseError("stack overflow")
 	}
 	// this section is inlined by go-inline
-	//   source function 'is' func (cs *callFrameStack) Push(v callFrame)  in _state.go
+	// source function is 'func (cs *callFrameStack) Push(v callFrame) ' in '_state.go'
 	{
 		cs := ls.stack
 		v := cf
@@ -768,7 +768,7 @@ func (ls *LState) pushCallFrame(cf callFrame, fn LValue, meta bool) { // +inline
 	}
 	newcf := ls.stack.Last()
 	// this section is inlined by go-inline
-	//   source function 'is' func (ls *LState) initCallFrame(cf *callFrame)  in _state.go
+	// source function is 'func (ls *LState) initCallFrame(cf *callFrame) ' in '_state.go'
 	{
 		cf := newcf
 		if cf.Fn.IsG {

table.go

@@ -48,6 +48,7 @@ func newLTable(acap int, hcap int) *LTable {
 	return tb
 }
 
+// Len returns length of this LTable.
 func (tb *LTable) Len() int {
 	if tb.array == nil {
 		return 0
@@ -63,13 +64,15 @@ func (tb *LTable) Len() int {
 	return 0
 }
 
+// Append appends a given LValue to this LTable.
 func (tb *LTable) Append(value LValue) {
 	if tb.array == nil {
 		tb.array = make([]LValue, 0, defaultArrayCap)
 	}
 	tb.array = append(tb.array, value)
 }
 
+// Insert inserts a given LValue at position `i` in this table.
 func (tb *LTable) Insert(i int, value LValue) {
 	if tb.array == nil {
 		tb.array = make([]LValue, 0, defaultArrayCap)
@@ -88,6 +91,7 @@ func (tb *LTable) Insert(i int, value LValue) {
 	tb.array[i] = value
 }
 
+// MaxN returns a maximum number key that nil value does not exist before it.
 func (tb *LTable) MaxN() int {
 	if tb.array == nil {
 		return 0
@@ -100,6 +104,7 @@ func (tb *LTable) MaxN() int {
 	return 0
 }
 
+// Remove removes from this table the element at a given position.
 func (tb *LTable) Remove(pos int) LValue {
 	if tb.array == nil {
 		return LNil
@@ -122,6 +127,9 @@ func (tb *LTable) Remove(pos int) LValue {
 	return oldval
 }
 
+// RawSet sets a given LValue to a given index without the __newindex metamethod.
+// It is recommended to use `RawSetString` or `RawSetInt` for performance
+// if you already know the given LValue is a string or number.
 func (tb *LTable) RawSet(key LValue, value LValue) {
 	switch v := key.(type) {
 	case LNumber:
@@ -152,6 +160,7 @@ func (tb *LTable) RawSet(key LValue, value LValue) {
 	tb.RawSetH(key, value)
 }
 
+// RawSetInt sets a given LValue at a position `key` without the __newindex metamethod.
 func (tb *LTable) RawSetInt(key int, value LValue) {
 	if key < 1 || key >= MaxArrayIndex {
 		tb.RawSetH(LNumber(key), value)
@@ -175,6 +184,7 @@ func (tb *LTable) RawSetInt(key int, value LValue) {
 	}
 }
 
+// RawSetString sets a given LValue to a given string index without the __newindex metamethod.
 func (tb *LTable) RawSetString(key string, value LValue) {
 	if tb.strdict == nil {
 		tb.strdict = make(map[string]LValue, defaultHashCap)
@@ -186,6 +196,7 @@ func (tb *LTable) RawSetString(key string, value LValue) {
 	}
 }
 
+// RawSetH sets a given LValue to a given index without the __newindex metamethod.
 func (tb *LTable) RawSetH(key LValue, value LValue) {
 	if s, ok := key.(LString); ok {
 		tb.RawSetString(string(s), value)
@@ -202,6 +213,7 @@ func (tb *LTable) RawSetH(key LValue, value LValue) {
 	}
 }
 
+// RawGet returns an LValue associated with a given key without __index metamethod.
 func (tb *LTable) RawGet(key LValue) LValue {
 	switch v := key.(type) {
 	case LNumber:
@@ -233,6 +245,7 @@ func (tb *LTable) RawGet(key LValue) LValue {
 	return LNil
 }
 
+// RawGetInt returns an LValue at position `key` without __index metamethod.
 func (tb *LTable) RawGetInt(key int) LValue {
 	if tb.array == nil {
 		return LNil
@@ -244,6 +257,7 @@ func (tb *LTable) RawGetInt(key int) LValue {
 	return tb.array[index]
 }
 
+// RawGet returns an LValue associated with a given key without __index metamethod.
 func (tb *LTable) RawGetH(key LValue) LValue {
 	if s, sok := key.(LString); sok {
 		if tb.strdict == nil {
@@ -263,6 +277,7 @@ func (tb *LTable) RawGetH(key LValue) LValue {
 	return LNil
 }
 
+// RawGetString returns an LValue associated with a given key without __index metamethod.
 func (tb *LTable) RawGetString(key string) LValue {
 	if tb.strdict == nil {
 		return LNil
@@ -273,6 +288,7 @@ func (tb *LTable) RawGetString(key string) LValue {
 	return LNil
 }
 
+// ForEach iterates over this table of elements, yielding each in turn to a given function.
 func (tb *LTable) ForEach(cb func(LValue, LValue)) {
 	if tb.array != nil {
 		for i, v := range tb.array {
@@ -297,6 +313,7 @@ func (tb *LTable) ForEach(cb func(LValue, LValue)) {
 	}
 }
 
+// This function is equivalent to lua_next ( http://www.lua.org/manual/5.1/manual.html#lua_next ).
 func (tb *LTable) Next(key LValue) (LValue, LValue) {
 	// TODO: inefficient way
 	if key == LNil {

value.go

@@ -36,8 +36,14 @@ type LValue interface {
 	assertFunction() (*LFunction, bool)
 }
 
+// LVIsFalse returns true if a given LValue is a nil or false otherwise false.
 func LVIsFalse(v LValue) bool { return v == LNil || v == LFalse }
-func LVAsBool(v LValue) bool  { return v != LNil && v != LFalse }
+
+// LVIsFalse returns false if a given LValue is a nil or false otherwise true.
+func LVAsBool(v LValue) bool { return v != LNil && v != LFalse }
+
+// LVAsString returns string representation of a given LValue
+// if the LValue is a string or number, otherwise an empty string.
 func LVAsString(v LValue) string {
 	switch sn := v.(type) {
 	case LString, LNumber:
@@ -47,6 +53,8 @@ func LVAsString(v LValue) string {
 	}
 }
 
+// LVCanConvToString returns true if a given LValue is a string or number
+// otherwise false.
 func LVCanConvToString(v LValue) bool {
 	switch v.(type) {
 	case LString, LNumber:
@@ -56,6 +64,7 @@ func LVCanConvToString(v LValue) bool {
 	}
 }
 
+// LVAsNumber tries to convert a given LValue to a number.
 func LVAsNumber(v LValue) LNumber {
 	switch lv := v.(type) {
 	case LNumber: