feat: implement new docgen featuring top-comment validation

docgen/docgen.lua

@@ -28,7 +28,7 @@ local ts_utils = ts.get_ts_utils()
 ---@return table #A list of paths to every module's `module.lua` file
 docgen.aggregate_module_files = function()
     return vim.fs.find("module.lua", {
-        path = vim.fn.fnamemodify(debug.getinfo(1, "S").source:sub(2), ":p:h"),
+        path = "..",
         type = "file",
         limit = math.huge,
     })
@@ -106,6 +106,27 @@ docgen.parse_top_comment = function(comment)
     return result
 end
 
+--- TODO
+---@param top_comment TopComment #The comment to check for errors
+---@return string|TopComment #An error string or the comment itself
+docgen.check_top_comment_integrity = function(top_comment)
+    local tc = vim.tbl_deep_extend("keep", top_comment, {
+        title = "",
+        summary = "",
+        markdown = {},
+    })
+
+    if not tc.file then
+        return "no `File:` field provided."
+    elseif tc.summary:sub(tc.summary:len()) ~= "." then
+        return "summary does not end with a full stop."
+    elseif tc.title:find("neorg") then
+        return "`neorg` written with lowercase letter. Use uppercase instead."
+    end
+
+    return top_comment
+end
+
 
 
 return docgen

docgen/init.lua

@@ -2,15 +2,19 @@ local docgen = require("docgen")
 local modules = {}
 
 for _, file in ipairs(docgen.aggregate_module_files()) do
-    local buffer = docgen.open_file(file)
+    local buffer = docgen.open_file(vim.fn.fnamemodify(file, ":p"))
 
     local top_comment = docgen.get_module_top_comment(buffer)
 
     if not top_comment then
         goto continue
     end
 
-    top_comment = docgen.parse_top_comment(top_comment)
+    local docgen_data = docgen.check_top_comment_integrity(docgen.parse_top_comment(top_comment))
+
+    if type(docgen_data) == "string" then
+        log.error("Error when parsing module '" .. file .. "': " .. docgen_data)
+    end
 
     ::continue::
 end

lua/neorg/modules/core/itero/module.lua

@@ -1,5 +1,6 @@
 --[[
---
+    File: Itero
+    Summary: Module designed to continue lists, headings and other iterables.
 --]]
 
 local module = neorg.modules.create("core.itero")