docs: create doc generator

_docgenerator/.gitignore

@@ -0,0 +1 @@
+.cache/

_docgenerator/example.txt

@@ -0,0 +1,8 @@
+// lua_upvalueid
+/*
+ * [-0, +0, –]
+ * Returns a unique identifier for the upvalue numbered n from the closure at index funcindex.
+*/
+func (L *State) UpvalueIndex(n int) int {
+	return int(C.clua_upvalueindex(C.int32_t(n)))
+}

_docgenerator/go.mod

@@ -0,0 +1,10 @@
+module docgen
+
+go 1.23.4
+
+require github.com/PuerkitoBio/goquery v1.10.0
+
+require (
+	github.com/andybalholm/cascadia v1.3.2 // indirect
+	golang.org/x/net v0.29.0 // indirect
+)

_docgenerator/go.sum

@@ -0,0 +1,40 @@
+github.com/PuerkitoBio/goquery v1.10.0 h1:6fiXdLuUvYs2OJSvNRqlNPoBm6YABE226xrbavY5Wv4=
+github.com/PuerkitoBio/goquery v1.10.0/go.mod h1:TjZZl68Q3eGHNBA8CWaxAN7rOU1EbDz3CWuolcO5Yu4=
+github.com/andybalholm/cascadia v1.3.2 h1:3Xi6Dw5lHF15JtdcmAHD3i1+T8plmv7BQ/nsViSLyss=
+github.com/andybalholm/cascadia v1.3.2/go.mod h1:7gtRlve5FxPPgIgX36uWBX58OdBsSS6lUvCFb+h7KvU=
+github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
+golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
+golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
+golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
+golang.org/x/net v0.9.0/go.mod h1:d48xBJpPfHeWQsugry2m+kC02ZBRGRgulfHnEXEuWns=
+golang.org/x/net v0.29.0 h1:5ORfpBpCs4HzDYoodCDBbwHzdR5UrLBZ3sOnUJmFoHo=
+golang.org/x/net v0.29.0/go.mod h1:gLkgy8jTGERgjzMic6DS9+SP0ajcu6Xu3Orq/SpETg0=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.7.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
+golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
+golang.org/x/term v0.7.0/go.mod h1:P32HKFT3hSsZrRxla30E9HqToFYAQPCMs/zFMBUFqPY=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
+golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
+golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
+golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=

_docgenerator/main.go

@@ -0,0 +1,188 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/PuerkitoBio/goquery"
+)
+
+var (
+	flagDoWrite    = flag.Bool("write", false, "Write to the opened file")
+	flagLuaVersion = flag.String("luaversion", "5.1", "Lua documentation version")
+	// flagHelp       = flag.Bool("help", false, "Show help")
+	// flagHelpShort  = flag.Bool("h", false, "Show help")
+)
+
+func main() {
+	flag.Parse()
+	// if *flagHelp || *flagHelpShort {
+	// 	flag.Usage()
+	// 	return
+	// }
+	if len(os.Args) < 2 {
+		fmt.Printf("Usage: %s [-write] [-luaversion <version | 5.1>] <go-file> ", os.Args[0])
+		os.Exit(1)
+	}
+
+	goFile := flag.Arg(0)
+
+	// Read Go code from file
+	goCode, err := os.ReadFile(goFile)
+	if err != nil {
+		fmt.Println("Error reading Go file:", err)
+		os.Exit(1)
+	}
+
+	// Fetch or load cached Lua documentation
+	luadocs, err := getCachedLuaDocs()
+	if err != nil {
+		fmt.Println("Error fetching Lua documentation:", err)
+		os.Exit(1)
+	}
+
+	luaFuncs, err := parseLuaDocs(luadocs)
+	if err != nil {
+		fmt.Println("Error parsing Lua documentation:", err)
+		os.Exit(1)
+	}
+
+	// Add comments to the Go code
+	annotatedCode := addDocumentation(string(goCode), luaFuncs)
+
+	if *flagDoWrite {
+		err := os.WriteFile(goFile, []byte(annotatedCode), 0644)
+		if err != nil {
+			fmt.Println("Error writing annotated code to file:", err)
+			os.Exit(1)
+		}
+		fmt.Println("Annotated code written back to", goFile)
+	} else {
+		fmt.Println(annotatedCode)
+	}
+}
+
+// Fetch or load cached Lua documentation
+func getCachedLuaDocs() (string, error) {
+	cacheDir := ".cache"
+	cacheFile := filepath.Join(cacheDir, fmt.Sprintf("lua_manual_%s.html", *flagLuaVersion))
+
+	// Ensure cache directory exists
+	if _, err := os.Stat(cacheDir); os.IsNotExist(err) {
+		err := os.Mkdir(cacheDir, 0755)
+		if err != nil {
+			return "", err
+		}
+	}
+
+	// Check if cached file exists
+	var body string
+	if _, err := os.Stat(cacheFile); err == nil {
+		cachedBody, err := os.ReadFile(cacheFile)
+		if err != nil {
+			return "", err
+		}
+		body = string(cachedBody)
+	} else {
+		// Fetch Lua manual and cache it
+		url := fmt.Sprintf("https://www.lua.org/manual/%s/manual.html", *flagLuaVersion) // Change version as needed
+		resp, err := http.Get(url)
+		if err != nil {
+			return "", err
+		}
+		defer resp.Body.Close()
+
+		if resp.StatusCode < 200 || resp.StatusCode > 299 {
+			return "", fmt.Errorf("unexpected error code for lua doc: %d", resp.StatusCode)
+		}
+
+		bodyBytes, err := io.ReadAll(resp.Body)
+		if err != nil {
+			return "", err
+		}
+		body = string(bodyBytes)
+
+		err = os.WriteFile(cacheFile, bodyBytes, 0644)
+		if err != nil {
+			return "", err
+		}
+	}
+	return body, nil
+}
+
+type LuaFunction struct {
+	Name        string
+	StackEffect string
+	Signature   string
+	Description string
+}
+
+func parseLuaDocs(html string) (map[string]LuaFunction, error) {
+	doc, err := goquery.NewDocumentFromReader(strings.NewReader(html))
+	if err != nil {
+		return nil, err
+	}
+
+	functions := map[string]LuaFunction{}
+
+	doc.Find("hr + h3").Has("a[name^='lua_']").Each(func(i int, s *goquery.Selection) {
+		var luaFunc LuaFunction
+
+		// Extract name
+		luaFunc.Name = s.Find("code").Text()
+
+		// Extract stack effect
+		if goquery.NodeName(s.Next()) == "p" {
+			luaFunc.StackEffect = strings.TrimSpace(s.Next().Text())
+			s = s.Next()
+		}
+
+		if goquery.NodeName(s.Next()) == "pre" {
+			luaFunc.Signature = strings.TrimSpace(s.Next().Text())
+			s = s.Next()
+		}
+
+		if goquery.NodeName(s.Next()) == "p" {
+			luaFunc.Description = strings.ReplaceAll(strings.TrimSpace(s.Next().Text()), "\n", " ")
+			// s = s.Next()
+		}
+
+		functions[strings.ToLower(luaFunc.Name)] = luaFunc
+	})
+
+	return functions, nil
+}
+
+func removeOldDocumentation(code string) string {
+	blockCommentRegex := regexp.MustCompile(`(?m)(// lua_.*$\n)/\*\n(?: \*.*$\n)+[ ]?\*/$\n`)
+	return blockCommentRegex.ReplaceAllString(code, "$1")
+}
+
+// Add documentation comments to the Go code
+func addDocumentation(code string, luaFuncs map[string]LuaFunction) string {
+	code = removeOldDocumentation(code)
+
+	lines := strings.Split(code, "\n")
+	var annotatedLines []string
+
+	for _, line := range lines {
+		annotatedLines = append(annotatedLines, line)
+		if strings.HasPrefix(line, "// lua_") {
+			functionName := strings.TrimPrefix(line, "// ")
+			if doc, exists := luaFuncs[functionName]; exists {
+				annotatedLines = append(annotatedLines, "/*")
+				annotatedLines = append(annotatedLines, " * "+doc.StackEffect)
+				annotatedLines = append(annotatedLines, " * "+doc.Description)
+				annotatedLines = append(annotatedLines, " */")
+			}
+		}
+	}
+
+	return strings.Join(annotatedLines, "\n")
+}