feat(docgen): add comment integrity checking logic

docgen/docgen.lua

@@ -386,4 +386,17 @@ docgen.generators = {
     end,
 }
 
+--- Check the integrity of the description comments found in configuration blocks
+---@param comment string #The comment to check the integrity of
+---@return nil|string #`nil` for success, `string` if there was an error
+docgen.check_comment_integrity = function(comment)
+    if comment:match("^%s*%-%-+%s*") then
+        return "found leading `--` comment text."
+    elseif comment:sub(1, 1):upper() ~= comment:sub(1, 1) then
+        return "comment does not begin with a capital letter."
+    elseif comment:find(" neorg ") then
+        return "`neorg` written with lowercase letter. Use uppercase instead."
+    end
+end
+
 return docgen

docgen/init.lua

@@ -70,7 +70,16 @@ for module_name, module in pairs(modules) do
             end
 
             comments = table.concat(comments, "\n")
-            log.warn(comments)
+
+            local error = docgen.check_comment_integrity(comments)
+
+            if type(error) == "string" then
+                -- Get the exact location of the error with data.node and the file it was contained in
+                local start_row, start_col = data.node:start()
+
+                vim.notify(("Error when parsing annotation in module '%s' on line (%d, %d): %s"):format(module_name, start_row, start_col, error))
+                return
+            end
         end)
     end
 end