Skip to content

Commit fc44bc4

Browse files
NoryiENoryiE
committed
Docs Parser fixes
1 parent b5f9ced commit fc44bc4

File tree

4 files changed

+57
-62
lines changed

4 files changed

+57
-62
lines changed

‎src/elements/Tree.lua‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ local VisualElement = require("elements/VisualElement")
22
local sub = string.sub
33
---@cofnigDescription The tree element provides a hierarchical view of nodes that can be expanded and collapsed, with support for selection and scrolling.
44

5+
56
--- This is the tree class. It provides a hierarchical view of nodes that can be expanded and collapsed,
67
--- with support for selection and scrolling.
78
---@class Tree : VisualElement

‎tools/BasaltDoc/init.lua‎

Lines changed: 23 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -4,22 +4,26 @@ local defaultPath = package.path
44
if fs then
55
local args = {...}
66
local docsPath = fs.getDir(args[2])
7-
local format = "path;/path/?.lua;/path/?/init.lua;"
7+
local format = "path/?.lua;path/?/init.lua;"
88
local main = format:gsub("path", docsPath)
99
package.path = main.."rom/?;"..defaultPath
10+
else
11+
local format = "path/?.lua;path/?/init.lua;"
12+
local main = format:gsub("path", "tools/BasaltDoc")
13+
package.path = main .. ";" .. defaultPath
1014
end
1115

12-
local ok1, classParser = pcall(require, "parsers.classParser")
16+
local classParser = require("parsers.classParser")
1317

14-
local ok2, functionParser = pcall(require, "parsers.functionParser")
18+
local functionParser = require("parsers.functionParser")
1519

16-
local ok3, propertyParser = pcall(require, "parsers.propertyParser")
20+
local propertyParser = require("parsers.propertyParser")
1721

18-
local ok4, eventParser = pcall(require, "parsers.eventParser")
22+
local eventParser = require("parsers.eventParser")
1923

20-
local ok6, globalParser = pcall(require, "parsers.globalParser")
24+
local globalParser = require("parsers.globalParser")
2125

22-
local ok5, markdownGenerator = pcall(require, "utils.markdownGenerator")
26+
local markdownGenerator = require("utils.markdownGenerator")
2327

2428
BasaltDoc.annotationHandlers = {}
2529

@@ -141,11 +145,11 @@ BasaltDoc.registerAnnotation("@globalDescription", function(target, args)
141145
end
142146
end)
143147

144-
if ok1 then classParser.setHandlers(BasaltDoc.annotationHandlers) end
145-
if ok2 then functionParser.setHandlers(BasaltDoc.annotationHandlers) end
146-
if ok3 then propertyParser.setHandlers(BasaltDoc.annotationHandlers) end
147-
if ok4 then eventParser.setHandlers(BasaltDoc.annotationHandlers) end
148-
if ok6 then globalParser.setHandlers(BasaltDoc.annotationHandlers) end
148+
if classParser then classParser.setHandlers(BasaltDoc.annotationHandlers) end
149+
if functionParser then functionParser.setHandlers(BasaltDoc.annotationHandlers) end
150+
if propertyParser then propertyParser.setHandlers(BasaltDoc.annotationHandlers) end
151+
if eventParser then eventParser.setHandlers(BasaltDoc.annotationHandlers) end
152+
if globalParser then globalParser.setHandlers(BasaltDoc.annotationHandlers) end
149153

150154
----------------------------------------------------------------
151155
-- Main Parser
@@ -174,7 +178,7 @@ function BasaltDoc.parse(content)
174178
if i <= #rawLines and rawLines[i]:match("%]%]") then
175179
i = i + 1
176180
end
177-
if #globalAnnotations > 0 and ok6 then
181+
if #globalAnnotations > 0 and globalParser then
178182
local global = globalParser.parse(globalAnnotations, table.concat(globalAnnotations, "\n"))
179183
ast.global = global
180184
end
@@ -211,25 +215,25 @@ function BasaltDoc.parse(content)
211215
elseif #annotationBuffer > 0 then
212216
local nextLine = lines[i]
213217
local skip = false
214-
if nextLine and nextLine:match("^function") and currentClass and ok2 then
218+
if nextLine and nextLine:match("^function") and currentClass and functionParser then
215219
local fn = functionParser.parse(annotationBuffer, nextLine)
216220
if fn then
217221
table.insert(currentClass.functions, fn)
218222
end
219223
skip = true
220224
elseif firstTag then
221-
if firstTag == "@class" and ok1 then
225+
if firstTag == "@class" and classParser then
222226
local class = classParser.parse(annotationBuffer, table.concat(annotationBuffer, "\n"))
223227
if class and not class.skip then
224228
table.insert(ast.classes, class)
225229
currentClass = class
226230
end
227-
elseif firstTag == "@property" and currentClass and ok3 then
231+
elseif firstTag == "@property" and currentClass and propertyParser then
228232
local prop = propertyParser.parse(annotationBuffer, table.concat(annotationBuffer, "\n"))
229233
if prop then
230234
table.insert(currentClass.properties, prop)
231235
end
232-
elseif firstTag == "@event" and currentClass and ok4 then
236+
elseif firstTag == "@event" and currentClass and eventParser then
233237
local evt = eventParser.parse(annotationBuffer, table.concat(annotationBuffer, "\n"))
234238
if evt then
235239
table.insert(currentClass.events, evt)
@@ -246,7 +250,7 @@ function BasaltDoc.parse(content)
246250
end
247251

248252
if #annotationBuffer > 0 and firstTag then
249-
if firstTag == "@class" and ok1 then
253+
if firstTag == "@class" and classParser then
250254
local class = classParser.parse(annotationBuffer, table.concat(annotationBuffer, "\n"))
251255
if class and not class.skip then
252256
table.insert(ast.classes, class)
@@ -259,7 +263,7 @@ function BasaltDoc.parse(content)
259263
end
260264

261265
function BasaltDoc.generateMarkdown(ast)
262-
if ok5 then
266+
if markdownGenerator then
263267
local result = markdownGenerator.generate(ast)
264268
return result
265269
else

‎tools/BasaltDoc/parsers/functionParser.lua‎

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@ local helper = require("utils.helper")
22
local functionParser = {}
33

44
function functionParser.parse(annotations, line)
5-
local name = line:match("^function%s+([%w_%.]+[:.]?[%w_]+)") or line:match("^function%s+([%w_]+)")
6-
if not name then
5+
local funcName = line:match("function ([%w_%.]+:?[%w_]*)")
6+
if not funcName then
77
print("Warning: Could not extract function name from line: " .. line)
88
return nil
99
end
1010
local f = {
1111
type = "function",
12-
name = name,
12+
name = funcName,
1313
description = nil,
1414
shortDescription = nil,
1515
params = {},
@@ -21,17 +21,14 @@ function functionParser.parse(annotations, line)
2121
helper.applyAnnotations(annotations, f, functionParser.handlers)
2222
end
2323

24-
local funcName = line:match("function ([%w_%.]+)")
25-
if funcName then
26-
if funcName:find(":") then
27-
f.name = funcName:match(":([%w_]+)")
28-
elseif funcName:find("%.") then
29-
f.name = funcName:match("%.([%w_]+)")
30-
else
31-
f.name = funcName
32-
end
24+
if funcName:find(":") then
25+
f.name = funcName:match(":([%w_]+)")
26+
elseif funcName:find("%.") then
27+
f.name = funcName:match("%.([%w_]+)")
28+
else
29+
f.name = funcName
3330
end
34-
31+
3532
if line:match("function [%w_%.]+:") then
3633
f.static = false
3734
else

‎tools/generate-docs.lua‎

Lines changed: 23 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
1-
-- generate-docs.lua
2-
3-
-- Argumente
41
local arg = arg or {...}
52
local SRC_DIR = arg[1] or "src"
63
local OUT_DIR = arg[2] or "build_docs/docs/references"
@@ -9,10 +6,6 @@ package.path = package.path .. ";./tools/?.lua"
96

107
local BasaltDoc = require("tools/BasaltDoc")
118

12-
--------------------------------------------------------
13-
-- Filesystem Abstraction
14-
--------------------------------------------------------
15-
169
local fileSystem
1710

1811
if fs then
@@ -25,7 +18,9 @@ if fs then
2518
open = function(path, mode) return fs.open(path, mode) end,
2619
getDir = fs.getDir,
2720
readAll = function(file) return file.readAll() end,
28-
write = function(file, data) file.write(data) end,
21+
write = function(file, data)
22+
file.write(data)
23+
end,
2924
close = function(file) file.close() end
3025
}
3126
else
@@ -90,81 +85,79 @@ else
9085
}
9186
end
9287

93-
--------------------------------------------------------
94-
-- Main
95-
--------------------------------------------------------
96-
9788
print("Starting documentation generation...")
98-
print("Source directory: " .. SRC_DIR)
99-
print("Output directory: " .. OUT_DIR)
10089

10190
if not fileSystem.exists(OUT_DIR) then
102-
print("Output directory does not exist, creating it...")
10391
fileSystem.makeDir(OUT_DIR)
104-
else
105-
print("Output directory already exists")
10692
end
10793

10894
local function getLuaFiles(dir)
109-
print("Scanning directory: " .. dir)
11095
if not fileSystem.exists(dir) then
111-
print("Directory does not exist: " .. dir)
11296
return {}
11397
end
11498

11599
local files = {}
116100
local list = fileSystem.list(dir)
117-
print("Found " .. #list .. " items in " .. dir)
118101

119102
for _, item in ipairs(list) do
120103
local path = fileSystem.combine(dir, item)
121104
if fileSystem.isDir(path) then
122-
print(" -> Directory, scanning recursively: " .. path)
123105
local subFiles = getLuaFiles(path)
124106
for _, subFile in ipairs(subFiles) do
125107
table.insert(files, subFile)
126108
end
127109
elseif item:match("%.lua$") then
128-
print(" -> Lua file found: " .. path)
129110
table.insert(files, path)
130-
else
131-
print(" -> Skipping: " .. item)
132111
end
133112
end
134113
return files
135114
end
136115

137116
local luaFiles = getLuaFiles(SRC_DIR)
138-
print("Found " .. #luaFiles .. " Lua files to process")
139117

140118
for _, filePath in ipairs(luaFiles) do
141119
local file = fileSystem.open(filePath, "r")
142120
if file then
143121
local content = fileSystem.readAll(file)
144122
fileSystem.close(file)
145123

146-
local ast = BasaltDoc.parse(content)
147-
local markdown = BasaltDoc.generateMarkdown(ast)
124+
if not content or #content == 0 then
125+
print("Warning: Empty file:", filePath)
126+
end
148127

149-
local relativePath = filePath:gsub("^" .. SRC_DIR .. "/", ""):gsub("%.lua$", ".md")
128+
local relativePath = filePath:gsub("^" .. SRC_DIR .. "/?", ""):gsub("%.lua$", ".md")
150129
local outPath = fileSystem.combine(OUT_DIR, relativePath)
151130

131+
local ast = BasaltDoc.parse(content)
132+
133+
local markdown = BasaltDoc.generateMarkdown(ast)
134+
152135
local outDir = fileSystem.getDir(outPath)
153136
if outDir and outDir ~= "" and not fileSystem.exists(outDir) then
154137
fileSystem.makeDir(outDir)
155138
end
156139

157140
local outFile = fileSystem.open(outPath, "w")
158141
if outFile then
159-
fileSystem.write(outFile, table.concat(markdown, "\n"))
142+
if not markdown or (type(markdown) == "table" and #markdown == 0) or (type(markdown) == "string" and #markdown == 0) then
143+
print("Warning: Empty markdown for", filePath)
144+
fileSystem.write(outFile, "!! EMPTY MARKDOWN GENERATED !!\n")
145+
else
146+
if type(markdown) == "table" then
147+
fileSystem.write(outFile, table.concat(markdown, "\n"))
148+
else
149+
fileSystem.write(outFile, tostring(markdown))
150+
end
151+
end
160152
fileSystem.close(outFile)
161153
print("Generated: " .. outPath)
162154
else
163155
print("Error writing: " .. outPath)
164156
end
157+
165158
else
166159
print("Error reading: " .. filePath)
167160
end
168161
end
169162

170-
print("Documentation generation complete.")
163+
print("Documentation generation complete.")

0 commit comments

Comments
 (0)