diff --git a/src/elements/Tree.lua b/src/elements/Tree.lua index 070d0d7..b3711e7 100644 --- a/src/elements/Tree.lua +++ b/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 diff --git a/tools/BasaltDoc/init.lua b/tools/BasaltDoc/init.lua index 1796ab8..2eb906f 100644 --- a/tools/BasaltDoc/init.lua +++ b/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 ok2 then functionParser.setHandlers(BasaltDoc.annotationHandlers) end -if ok3 then propertyParser.setHandlers(BasaltDoc.annotationHandlers) end -if ok4 then eventParser.setHandlers(BasaltDoc.annotationHandlers) end -if ok6 then globalParser.setHandlers(BasaltDoc.annotationHandlers) end +if classParser then classParser.setHandlers(BasaltDoc.annotationHandlers) end +if functionParser then functionParser.setHandlers(BasaltDoc.annotationHandlers) end +if propertyParser then propertyParser.setHandlers(BasaltDoc.annotationHandlers) end +if eventParser then eventParser.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 diff --git a/tools/BasaltDoc/parsers/functionParser.lua b/tools/BasaltDoc/parsers/functionParser.lua index edc7d9f..3e0895c 100644 --- a/tools/BasaltDoc/parsers/functionParser.lua +++ b/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_]+)") - if not name then + local funcName = line:match("function ([%w_%.]+:?[%w_]*)") + 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 then - if funcName:find(":") then - f.name = funcName:match(":([%w_]+)") - elseif funcName:find("%.") then - f.name = funcName:match("%.([%w_]+)") - else - f.name = funcName - end + if funcName:find(":") then + f.name = funcName:match(":([%w_]+)") + elseif funcName:find("%.") then + f.name = funcName:match("%.([%w_]+)") + else + f.name = funcName end - + if line:match("function [%w_%.]+:") then f.static = false else diff --git a/tools/generate-docs.lua b/tools/generate-docs.lua index 9f1f6e3..0a22e1b 100644 --- a/tools/generate-docs.lua +++ b/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) - local markdown = BasaltDoc.generateMarkdown(ast) + if not content or #content == 0 then + 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.") \ No newline at end of file