Docs Parser fixes

src/elements/Tree.lua

@@ -2,6 +2,7 @@ local VisualElement = require("elements/VisualElement")
 local sub = string.sub
 ---@cofnigDescription The tree element provides a hierarchical view of nodes that can be expanded and collapsed, with support for selection and scrolling.
 
+
 --- This is the tree class. It provides a hierarchical view of nodes that can be expanded and collapsed,
 --- with support for selection and scrolling.
 ---@class Tree : VisualElement

tools/BasaltDoc/init.lua

@@ -4,22 +4,26 @@ local defaultPath = package.path
 if fs then
     local args = {...}
     local docsPath = fs.getDir(args[2])
-    local format = "path;/path/?.lua;/path/?/init.lua;"
+    local format = "path/?.lua;path/?/init.lua;"
     local main = format:gsub("path", docsPath)
     package.path = main.."rom/?;"..defaultPath
+else
+    local format = "path/?.lua;path/?/init.lua;"
+    local main = format:gsub("path", "tools/BasaltDoc")
+    package.path = main .. ";" .. defaultPath
 end
 
-local ok1, classParser = pcall(require, "parsers.classParser")
+local classParser = require("parsers.classParser")
 
-local ok2, functionParser = pcall(require, "parsers.functionParser")
+local functionParser = require("parsers.functionParser")
 
-local ok3, propertyParser = pcall(require, "parsers.propertyParser")
+local propertyParser = require("parsers.propertyParser")
 
-local ok4, eventParser = pcall(require, "parsers.eventParser")
+local eventParser = require("parsers.eventParser")
 
-local ok6, globalParser = pcall(require, "parsers.globalParser")
+local globalParser = require("parsers.globalParser")
 
-local ok5, markdownGenerator = pcall(require, "utils.markdownGenerator")
+local markdownGenerator = require("utils.markdownGenerator")
 
 BasaltDoc.annotationHandlers = {}
 
@@ -141,11 +145,11 @@ BasaltDoc.registerAnnotation("@globalDescription", function(target, args)
     end
 end)
 
-if ok1 then classParser.setHandlers(BasaltDoc.annotationHandlers) end
+if classParser then classParser.setHandlers(BasaltDoc.annotationHandlers) end
-if ok2 then functionParser.setHandlers(BasaltDoc.annotationHandlers) end
+if functionParser then functionParser.setHandlers(BasaltDoc.annotationHandlers) end
-if ok3 then propertyParser.setHandlers(BasaltDoc.annotationHandlers) end
+if propertyParser then propertyParser.setHandlers(BasaltDoc.annotationHandlers) end
-if ok4 then eventParser.setHandlers(BasaltDoc.annotationHandlers) end
+if eventParser then eventParser.setHandlers(BasaltDoc.annotationHandlers) end
-if ok6 then globalParser.setHandlers(BasaltDoc.annotationHandlers) end
+if globalParser then globalParser.setHandlers(BasaltDoc.annotationHandlers) end
 
 ----------------------------------------------------------------
 -- Main Parser
@@ -174,7 +178,7 @@ function BasaltDoc.parse(content)
                 if i <= #rawLines and rawLines[i]:match("%]%]") then
                     i = i + 1
                 end
-                if #globalAnnotations > 0 and ok6 then
+                if #globalAnnotations > 0 and globalParser then
                     local global = globalParser.parse(globalAnnotations, table.concat(globalAnnotations, "\n"))
                     ast.global = global
                 end
@@ -211,25 +215,25 @@ function BasaltDoc.parse(content)
         elseif #annotationBuffer > 0 then
             local nextLine = lines[i]
             local skip = false
-            if nextLine and nextLine:match("^function") and currentClass and ok2 then
+            if nextLine and nextLine:match("^function") and currentClass and functionParser then
                 local fn = functionParser.parse(annotationBuffer, nextLine)
                 if fn then
                     table.insert(currentClass.functions, fn)
                 end
                 skip = true
             elseif firstTag then
-                if firstTag == "@class" and ok1 then
+                if firstTag == "@class" and classParser then
                     local class = classParser.parse(annotationBuffer, table.concat(annotationBuffer, "\n"))
                     if class and not class.skip then
                         table.insert(ast.classes, class)
                         currentClass = class
                     end
-                elseif firstTag == "@property" and currentClass and ok3 then
+                elseif firstTag == "@property" and currentClass and propertyParser then
                     local prop = propertyParser.parse(annotationBuffer, table.concat(annotationBuffer, "\n"))
                     if prop then
                         table.insert(currentClass.properties, prop)
                     end
-                elseif firstTag == "@event" and currentClass and ok4 then
+                elseif firstTag == "@event" and currentClass and eventParser then
                     local evt = eventParser.parse(annotationBuffer, table.concat(annotationBuffer, "\n"))
                     if evt then
                         table.insert(currentClass.events, evt)
@@ -246,7 +250,7 @@ function BasaltDoc.parse(content)
     end
 
     if #annotationBuffer > 0 and firstTag then
-        if firstTag == "@class" and ok1 then
+        if firstTag == "@class" and classParser then
             local class = classParser.parse(annotationBuffer, table.concat(annotationBuffer, "\n"))
             if class and not class.skip then
                 table.insert(ast.classes, class)
@@ -259,7 +263,7 @@ function BasaltDoc.parse(content)
 end
 
 function BasaltDoc.generateMarkdown(ast)
-    if ok5 then
+    if markdownGenerator then
         local result = markdownGenerator.generate(ast)
         return result
     else

tools/BasaltDoc/parsers/functionParser.lua

@@ -2,14 +2,14 @@ local helper = require("utils.helper")
 local functionParser = {}
 
 function functionParser.parse(annotations, line)
-    local name = line:match("^function%s+([%w_%.]+[:.]?[%w_]+)") or line:match("^function%s+([%w_]+)")
+    local funcName = line:match("function ([%w_%.]+:?[%w_]*)")
-    if not name then
+    if not funcName then
         print("Warning: Could not extract function name from line: " .. line)
         return nil
     end
     local f = {
         type = "function",
-        name = name,
+        name = funcName,
         description = nil,
         shortDescription = nil,
         params = {},
@@ -21,17 +21,14 @@ function functionParser.parse(annotations, line)
         helper.applyAnnotations(annotations, f, functionParser.handlers)
     end
 
-    local funcName = line:match("function ([%w_%.]+)")
+    if funcName:find(":") then
-    if funcName then
+        f.name = funcName:match(":([%w_]+)")
-        if funcName:find(":") then
+    elseif funcName:find("%.") then
-            f.name = funcName:match(":([%w_]+)")
+        f.name = funcName:match("%.([%w_]+)")
-        elseif funcName:find("%.") then
+    else
-            f.name = funcName:match("%.([%w_]+)")
+        f.name = funcName
-        else
-            f.name = funcName
-        end
     end
-
+    
     if line:match("function [%w_%.]+:") then
         f.static = false
     else

tools/generate-docs.lua

@@ -1,6 +1,3 @@
--- generate-docs.lua
-
--- Argumente
 local arg = arg or {...}
 local SRC_DIR = arg[1] or "src"
 local OUT_DIR = arg[2] or "build_docs/docs/references"
@@ -9,10 +6,6 @@ package.path = package.path .. ";./tools/?.lua"
 
 local BasaltDoc = require("tools/BasaltDoc")
 
---------------------------------------------------------
--- Filesystem Abstraction
---------------------------------------------------------
-
 local fileSystem
 
 if fs then
@@ -25,7 +18,9 @@ if fs then
         open = function(path, mode) return fs.open(path, mode) end,
         getDir = fs.getDir,
         readAll = function(file) return file.readAll() end,
-        write = function(file, data) file.write(data) end,
+        write = function(file, data)
+            file.write(data)
+        end,
         close = function(file) file.close() end
     }
 else
@@ -90,52 +85,35 @@ else
     }
 end
 
---------------------------------------------------------
--- Main
---------------------------------------------------------
-
 print("Starting documentation generation...")
-print("Source directory: " .. SRC_DIR)
-print("Output directory: " .. OUT_DIR)
 
 if not fileSystem.exists(OUT_DIR) then
-    print("Output directory does not exist, creating it...")
     fileSystem.makeDir(OUT_DIR)
-else
-    print("Output directory already exists")
 end
 
 local function getLuaFiles(dir)
-    print("Scanning directory: " .. dir)
     if not fileSystem.exists(dir) then
-        print("Directory does not exist: " .. dir)
         return {}
     end
 
     local files = {}
     local list = fileSystem.list(dir)
-    print("Found " .. #list .. " items in " .. dir)
 
     for _, item in ipairs(list) do
         local path = fileSystem.combine(dir, item)
         if fileSystem.isDir(path) then
-            print("  -> Directory, scanning recursively: " .. path)
             local subFiles = getLuaFiles(path)
             for _, subFile in ipairs(subFiles) do
                 table.insert(files, subFile)
             end
         elseif item:match("%.lua$") then
-            print("  -> Lua file found: " .. path)
             table.insert(files, path)
-        else
-            print("  -> Skipping: " .. item)
         end
     end
     return files
 end
 
 local luaFiles = getLuaFiles(SRC_DIR)
-print("Found " .. #luaFiles .. " Lua files to process")
 
 for _, filePath in ipairs(luaFiles) do
     local file = fileSystem.open(filePath, "r")
@@ -143,12 +121,17 @@ for _, filePath in ipairs(luaFiles) do
         local content = fileSystem.readAll(file)
         fileSystem.close(file)
 
-        local ast = BasaltDoc.parse(content)
+        if not content or #content == 0 then
-        local markdown = BasaltDoc.generateMarkdown(ast)
+            print("Warning: Empty file:", filePath)
+        end
 
-        local relativePath = filePath:gsub("^" .. SRC_DIR .. "/", ""):gsub("%.lua$", ".md")
+        local relativePath = filePath:gsub("^" .. SRC_DIR .. "/?", ""):gsub("%.lua$", ".md")
         local outPath = fileSystem.combine(OUT_DIR, relativePath)
 
+        local ast = BasaltDoc.parse(content)
+
+        local markdown = BasaltDoc.generateMarkdown(ast)
+
         local outDir = fileSystem.getDir(outPath)
         if outDir and outDir ~= "" and not fileSystem.exists(outDir) then
             fileSystem.makeDir(outDir)
@@ -156,15 +139,25 @@ for _, filePath in ipairs(luaFiles) do
 
         local outFile = fileSystem.open(outPath, "w")
         if outFile then
-            fileSystem.write(outFile, table.concat(markdown, "\n"))
+            if not markdown or (type(markdown) == "table" and #markdown == 0) or (type(markdown) == "string" and #markdown == 0) then
+                print("Warning: Empty markdown for", filePath)
+                fileSystem.write(outFile, "!! EMPTY MARKDOWN GENERATED !!\n")
+            else
+                if type(markdown) == "table" then
+                    fileSystem.write(outFile, table.concat(markdown, "\n"))
+                else
+                    fileSystem.write(outFile, tostring(markdown))
+                end
+            end
             fileSystem.close(outFile)
             print("Generated: " .. outPath)
         else
             print("Error writing: " .. outPath)
         end
+
     else
         print("Error reading: " .. filePath)
     end
 end
 
-print("Documentation generation complete.")
+print("Documentation generation complete.")