docs: add documentation to methods

Author: TimVosch

lua/golua_c_lua51.go

@@ -124,21 +124,37 @@ func lualLoadFile(s *C.lua_State, filename *C.char) C.int {
 }
 
 // lua_equal
+/*
+ * [-0, +0, e]
+ * Returns 1 if the two values in acceptable indices index1 and index2 are equal, following the semantics of the Lua == operator (that is, may call metamethods). Otherwise returns 0. Also returns 0 if any of the indices is non valid.
+ */
 func (L *State) Equal(index1, index2 int) bool {
 	return C.lua_equal(L.s, C.int(index1), C.int(index2)) == 1
 }
 
 // lua_getfenv
+/*
+ * [-0, +1, -]
+ * Pushes onto the stack the environment table of the value at the given index.
+ */
 func (L *State) GetfEnv(index int) {
 	C.lua_getfenv(L.s, C.int(index))
 }
 
 // lua_lessthan
+/*
+ * [-0, +0, e]
+ * Returns 1 if the value at acceptable index index1 is smaller than the value at acceptable index index2, following the semantics of the Lua < operator (that is, may call metamethods). Otherwise returns 0. Also returns 0 if any of the indices is non valid.
+ */
 func (L *State) LessThan(index1, index2 int) bool {
 	return C.lua_lessthan(L.s, C.int(index1), C.int(index2)) == 1
 }
 
 // lua_setfenv
+/*
+ * [-1, +0, -]
+ * Pops a table from the stack and sets it as the new environment for the value at the given index. If the value at the given index is neither a function nor a thread nor a userdata, lua_setfenv returns 0. Otherwise it returns 1.
+ */
 func (L *State) SetfEnv(index int) {
 	C.lua_setfenv(L.s, C.int(index))
 }
@@ -148,16 +164,28 @@ func (L *State) ObjLen(index int) uint {
 }
 
 // lua_tointeger
+/*
+ * [-0, +0, -]
+ * Converts the Lua value at the given acceptable index to the signed integral type lua_Integer. The Lua value must be a number or a string convertible to a number (see §2.2.1); otherwise, lua_tointeger returns 0.
+ */
 func (L *State) ToInteger(index int) int {
 	return int(C.lua_tointeger(L.s, C.int(index)))
 }
 
 // lua_tonumber
+/*
+ * [-0, +0, -]
+ * Converts the Lua value at the given acceptable index to the C type lua_Number (see lua_Number). The Lua value must be a number or a string convertible to a number (see §2.2.1); otherwise, lua_tonumber returns 0.
+ */
 func (L *State) ToNumber(index int) float64 {
 	return float64(C.lua_tonumber(L.s, C.int(index)))
 }
 
 // lua_yield
+/*
+ * [-?, +?, -]
+ * Yields a coroutine.
+ */
 func (L *State) Yield(nresults int) int {
 	return int(C.lua_yield(L.s, C.int(nresults)))
 }
@@ -170,41 +198,73 @@ func (L *State) pcall(nargs, nresults, errfunc int) int {
 func (L *State) GetGlobal(name string) { L.GetField(LUA_GLOBALSINDEX, name) }
 
 // lua_resume
+/*
+ * [-?, +?, -]
+ * Starts and resumes a coroutine in a given thread.
+ */
 func (L *State) Resume(narg int) int {
 	return int(C.lua_resume(L.s, C.int(narg)))
 }
 
 // lua_setglobal
+/*
+ * [-1, +0, e]
+ * Pops a value from the stack and sets it as the new value of global name. It is defined as a macro:
+ */
 func (L *State) SetGlobal(name string) {
 	Cname := C.CString(name)
 	defer C.free(unsafe.Pointer(Cname))
 	C.lua_setfield(L.s, C.int(LUA_GLOBALSINDEX), Cname)
 }
 
 // lua_insert
+/*
+ * [-1, +1, -]
+ * Moves the top element into the given valid index, shifting up the elements above this index to open space. Cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.
+ */
 func (L *State) Insert(index int) { C.lua_insert(L.s, C.int(index)) }
 
 // lua_remove
+/*
+ * [-1, +0, -]
+ * Removes the element at the given valid index, shifting down the elements above this index to fill the gap. Cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.
+ */
 func (L *State) Remove(index int) {
 	C.lua_remove(L.s, C.int(index))
 }
 
 // lua_replace
+/*
+ * [-1, +0, -]
+ * Moves the top element into the given position (and pops it), without shifting any element (therefore replacing the value at the given position).
+ */
 func (L *State) Replace(index int) {
 	C.lua_replace(L.s, C.int(index))
 }
 
 // lua_rawgeti
+/*
+ * [-0, +1, -]
+ * Pushes onto the stack the value t[n], where t is the value at the given valid index. The access is raw; that is, it does not invoke metamethods.
+ */
 func (L *State) RawGeti(index int, n int) {
 	C.lua_rawgeti(L.s, C.int(index), C.int(n))
 }
 
 // lua_rawseti
+/*
+ * [-1, +0, m]
+ * Does the equivalent of t[n] = v, where t is the value at the given valid index and v is the value at the top of the stack.
+ */
 func (L *State) RawSeti(index int, n int) {
 	C.lua_rawseti(L.s, C.int(index), C.int(n))
 }
 
 // lua_gc
+/*
+ * [-0, +0, e]
+ * Controls the garbage collector.
+ */
 func (L *State) GC(what, data int) int {
 	return int(C.lua_gc(L.s, C.int(what), C.int(data)))
 }

lua/golua_c_lua52.go

@@ -150,16 +150,28 @@ func (L *State) ObjLen(index int) uint {
 }
 
 // lua_tointeger
+/*
+ * [-0, +0, –]
+ * Equivalent to lua_tointegerx with isnum equal to NULL.
+ */
 func (L *State) ToInteger(index int) int {
 	return int(C.lua_tointegerx(L.s, C.int(index), nil))
 }
 
 // lua_tonumber
+/*
+ * [-0, +0, –]
+ * Equivalent to lua_tonumberx with isnum equal to NULL.
+ */
 func (L *State) ToNumber(index int) float64 {
 	return float64(C.lua_tonumberx(L.s, C.int(index), nil))
 }
 
 // lua_yield
+/*
+ * [-?, +?, –]
+ * This function is equivalent to lua_yieldk, but it has no continuation (see §4.7). Therefore, when the thread resumes, it returns to the function that called the function calling lua_yield.
+ */
 func (L *State) Yield(nresults int) int {
 	return int(C.lua_yieldk(L.s, C.int(nresults), 0, nil))
 }
@@ -176,11 +188,19 @@ func (L *State) GetGlobal(name string) {
 }
 
 // lua_resume
+/*
+ * [-?, +?, –]
+ * Starts and resumes a coroutine in a given thread.
+ */
 func (L *State) Resume(narg int) int {
 	return int(C.lua_resume(L.s, nil, C.int(narg)))
 }
 
 // lua_setglobal
+/*
+ * [-1, +0, e]
+ * Pops a value from the stack and sets it as the new value of global name.
+ */
 func (L *State) SetGlobal(name string) {
 	Cname := C.CString(name)
 	defer C.free(unsafe.Pointer(Cname))
@@ -203,29 +223,53 @@ func (L *State) OpenCoroutine() {
 }
 
 // lua_insert
+/*
+ * [-1, +1, –]
+ * Moves the top element into the given valid index, shifting up the elements above this index to open space. This function cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.
+ */
 func (L *State) Insert(index int) { C.lua_insert(L.s, C.int(index)) }
 
 // lua_remove
+/*
+ * [-1, +0, –]
+ * Removes the element at the given valid index, shifting down the elements above this index to fill the gap. This function cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.
+ */
 func (L *State) Remove(index int) {
 	C.lua_remove(L.s, C.int(index))
 }
 
 // lua_replace
+/*
+ * [-1, +0, –]
+ * Moves the top element into the given valid index without shifting any element (therefore replacing the value at the given index), and then pops the top element.
+ */
 func (L *State) Replace(index int) {
 	C.lua_replace(L.s, C.int(index))
 }
 
 // lua_rawgeti
+/*
+ * [-0, +1, –]
+ * Pushes onto the stack the value t[n], where t is the table at the given index. The access is raw; that is, it does not invoke metamethods.
+ */
 func (L *State) RawGeti(index int, n int) {
 	C.lua_rawgeti(L.s, C.int(index), C.int(n))
 }
 
 // lua_rawseti
+/*
+ * [-1, +0, e]
+ * Does the equivalent of t[n] = v, where t is the table at the given index and v is the value at the top of the stack.
+ */
 func (L *State) RawSeti(index int, n int) {
 	C.lua_rawseti(L.s, C.int(index), C.int(n))
 }
 
 // lua_gc
+/*
+ * [-0, +0, e]
+ * Controls the garbage collector.
+ */
 func (L *State) GC(what, data int) int {
 	return int(C.lua_gc(L.s, C.int(what), C.int(data)))
 }

lua/golua_c_lua53.go

@@ -150,16 +150,28 @@ func (L *State) ObjLen(index int) uint {
 }
 
 // lua_tointeger
+/*
+ * [-0, +0, –]
+ * Equivalent to lua_tointegerx with isnum equal to NULL.
+ */
 func (L *State) ToInteger(index int) int {
 	return int(C.lua_tointegerx(L.s, C.int(index), nil))
 }
 
 // lua_tonumber
+/*
+ * [-0, +0, –]
+ * Equivalent to lua_tonumberx with isnum equal to NULL.
+ */
 func (L *State) ToNumber(index int) float64 {
 	return float64(C.lua_tonumberx(L.s, C.int(index), nil))
 }
 
 // lua_yield
+/*
+ * [-?, +?, e]
+ * This function is equivalent to lua_yieldk, but it has no continuation (see §4.7). Therefore, when the thread resumes, it continues the function that called the function calling lua_yield.
+ */
 func (L *State) Yield(nresults int) int {
 	return int(C.lua_yieldk(L.s, C.int(nresults), 0, nil))
 }
@@ -176,11 +188,19 @@ func (L *State) GetGlobal(name string) {
 }
 
 // lua_resume
+/*
+ * [-?, +?, –]
+ * Starts and resumes a coroutine in the given thread L.
+ */
 func (L *State) Resume(narg int) int {
 	return int(C.lua_resume(L.s, nil, C.int(narg)))
 }
 
 // lua_setglobal
+/*
+ * [-1, +0, e]
+ * Pops a value from the stack and sets it as the new value of global name.
+ */
 func (L *State) SetGlobal(name string) {
 	Cname := C.CString(name)
 	defer C.free(unsafe.Pointer(Cname))
@@ -203,31 +223,55 @@ func (L *State) OpenCoroutine() {
 }
 
 // lua_insert
+/*
+ * [-1, +1, –]
+ * Moves the top element into the given valid index, shifting up the elements above this index to open space. This function cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.
+ */
 func (L *State) Insert(index int) { C.lua_rotate(L.s, C.int(index), 1) }
 
 // lua_remove
+/*
+ * [-1, +0, –]
+ * Removes the element at the given valid index, shifting down the elements above this index to fill the gap. This function cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.
+ */
 func (L *State) Remove(index int) {
 	C.lua_rotate(L.s, C.int(index), -1)
 	C.lua_settop(L.s, C.int(-2))
 }
 
 // lua_replace
+/*
+ * [-1, +0, –]
+ * Moves the top element into the given valid index without shifting any element (therefore replacing the value at that given index), and then pops the top element.
+ */
 func (L *State) Replace(index int) {
 	C.lua_copy(L.s, -1, C.int(index))
 	C.lua_settop(L.s, -2)
 }
 
 // lua_rawgeti
+/*
+ * [-0, +1, –]
+ * Pushes onto the stack the value t[n], where t is the table at the given index. The access is raw, that is, it does not invoke the __index metamethod.
+ */
 func (L *State) RawGeti(index int, n int) {
 	C.lua_rawgeti(L.s, C.int(index), C.longlong(n))
 }
 
 // lua_rawseti
+/*
+ * [-1, +0, m]
+ * Does the equivalent of t[i] = v, where t is the table at the given index and v is the value at the top of the stack.
+ */
 func (L *State) RawSeti(index int, n int) {
 	C.lua_rawseti(L.s, C.int(index), C.longlong(n))
 }
 
 // lua_gc
+/*
+ * [-0, +0, m]
+ * Controls the garbage collector.
+ */
 func (L *State) GC(what, data int) int {
 	return int(C.lua_gc(L.s, C.int(what), C.int(data)))
 }