Warn about missing '---comment', '@return' and '@param' annotations (#3)

All functions that have at least one such annotation should be fully annotated in that respect, because we find that partially annotating something leads to confusion.
However, all global functions must always be fully annotated, because they should be avoided in the first place, but if necessary then only with the maximum amount of documentation/support for those who use them!

We provide the following keys for the `diagnostics.disable` setting to specifically deactive these checks:
_missing-global-doc_: global function definitions which are not fully annotated.
_incomplete-signature-doc_: function definitions that have some annotations but are not fully annotated

2 files changed, 189 insertions, 0 deletions

diff --git a/script/core/diagnostics/incomplete-signature-doc.lua b/script/core/diagnostics/incomplete-signature-doc.lua
new file mode 100644
index 00000000..91f2db74
--- /dev/null
+++ b/script/core/diagnostics/incomplete-signature-doc.lua
@@ -0,0 +1,91 @@
+-- incomplete-signature-doc
+local files   = require 'files'
+local lang    = require 'language'
+local guide   = require "parser.guide"
+local await   = require 'await'
+
+local function findParam(docs, param)
+    if not docs then
+        return false
+    end
+
+    for _, doc in ipairs(docs) do
+        if doc.type == 'doc.param' then
+            if doc.param[1] == param then
+                return true
+            end
+        end
+    end
+
+    return false
+end
+
+local function findReturn(docs, index)
+    if not docs then
+        return false
+    end
+
+    for _, doc in ipairs(docs) do
+        if doc.type == 'doc.return' then
+            for _, ret in ipairs(doc.returns) do
+                if ret.returnIndex == index then
+                    return true
+                end
+            end
+        end
+    end
+
+    return false
+end
+
+---@async
+return function (uri, callback)
+    local state = files.getState(uri)
+    if not state then
+        return
+    end
+
+    if not state.ast then
+        return
+    end
+
+    ---@async
+    guide.eachSourceType(state.ast, 'function', function (source)
+        await.delay()
+
+        if not source.bindDocs then
+            return
+        end
+
+        local functionName = source.parent[1]
+
+        if #source.args > 0 then
+            for _, arg in ipairs(source.args) do
+                local argName = arg[1]
+                if argName ~= 'self' then
+                    if not findParam(source.bindDocs, argName) then
+                        callback {
+                            start   = arg.start,
+                            finish  = arg.finish,
+                            message = lang.script('DIAG_INCOMPLETE_SIGNATURE_DOC_PARAM', argName, functionName),
+                        }
+                    end
+                end
+            end
+        end
+
+        if  source.returns then
+            for _, ret in ipairs(source.returns) do
+                for index, expr in ipairs(ret) do
+                    if not findReturn(source.bindDocs, index) then
+                        callback {
+                            start   = expr.start,
+                            finish  = expr.finish,
+                            message = lang.script('DIAG_INCOMPLETE_SIGNATURE_DOC_RETURN', index, functionName),
+                        }
+                    end
+                end
+            end
+        end
+    end)
+end
diff --git a/script/core/diagnostics/missing-global-doc.lua b/script/core/diagnostics/missing-global-doc.lua
new file mode 100644
index 00000000..adcdf404
--- /dev/null
+++ b/script/core/diagnostics/missing-global-doc.lua
@@ -0,0 +1,98 @@
+local files   = require 'files'
+local lang    = require 'language'
+local guide   = require "parser.guide"
+local await   = require 'await'
+
+local function findParam(docs, param)
+    if not docs then
+        return false
+    end
+
+    for _, doc in ipairs(docs) do
+        if doc.type == 'doc.param' then
+            if doc.param[1] == param then
+                return true
+            end
+        end
+    end
+
+    return false
+end
+
+local function findReturn(docs, index)
+    if not docs then
+        return false
+    end
+
+    for _, doc in ipairs(docs) do
+        if doc.type == 'doc.return' then
+            for _, ret in ipairs(doc.returns) do
+                if ret.returnIndex == index then
+                    return true
+                end
+            end
+        end
+    end
+
+    return false
+end
+
+---@async
+return function (uri, callback)
+    local state = files.getState(uri)
+    if not state then
+        return
+    end
+
+    if not state.ast then
+        return
+    end
+
+    ---@async
+    guide.eachSourceType(state.ast, 'function', function (source)
+        await.delay()
+
+        if source.parent.type ~= 'setglobal' then
+            return
+        end
+
+        local functionName = source.parent[1]
+
+        if #source.args == 0 and not source.returns and not source.bindDocs then
+            callback {
+                start   = source.start,
+                finish  = source.finish,
+                message = lang.script('DIAG_MISSING_GLOBAL_DOC_COMMENT', functionName),
+            }
+        end
+
+        if #source.args > 0 then
+            for _, arg in ipairs(source.args) do
+                local argName = arg[1]
+                if argName ~= 'self' then
+                    if not findParam(source.bindDocs, argName) then
+                        callback {
+                            start   = arg.start,
+                            finish  = arg.finish,
+                            message = lang.script('DIAG_MISSING_GLOBAL_DOC_PARAM', argName, functionName),
+                        }
+                    end
+                end
+            end
+        end
+
+        if  source.returns then
+            for _, ret in ipairs(source.returns) do
+                for index, expr in ipairs(ret) do
+                    if not findReturn(source.bindDocs, index) then
+                        callback {
+                            start   = expr.start,
+                            finish  = expr.finish,
+                            message = lang.script('DIAG_MISSING_GLOBAL_DOC_RETURN', index, functionName),
+                        }
+                    end
+                end
+            end
+        end
+    end)
+end