Adapt incomplete-signature-doc to warn about incomplete, not missing docs (#9)

Previously, the diagnostic `incomplete-signature-doc` is ignoring fully
undocumented functions - but is already triggered by a simple comment.
This turns out to be impractical in a few cases, as it also forces a
full documentation of functions that should just be annotated with
`---@async` (and is therefore not yet fully compatible with
`await-in-sync`)

So this PR adapts the diagnostic to only warn about **incomplete**
signature docs, so it requires at least one `@param` or `@return`
annotation before a warning is given. (Otherwise, it would be a missing
signature doc, and there's separate diagnostics about that...)

1 files changed, 19 insertions, 0 deletions

diff --git a/script/core/diagnostics/incomplete-signature-doc.lua b/script/core/diagnostics/incomplete-signature-doc.lua
index c030e7ad..f91f22d2 100644
--- a/script/core/diagnostics/incomplete-signature-doc.lua
+++ b/script/core/diagnostics/incomplete-signature-doc.lua
@@ -38,6 +38,19 @@ local function findReturn(docs, index)
     return false
 end
 
+--- check if there's any signature doc (@param or @return), or just comments, @async, ...
+local function findSignatureDoc(docs)
+    if not docs then
+        return false
+    end
+    for _, doc in ipairs(docs) do
+        if doc.type == 'doc.return' or doc.type == 'doc.param' then
+            return true
+        end
+    end
+    return false
+end
+
 ---@async
 return function (uri, callback)
     local state = files.getState(uri)
@@ -59,6 +72,12 @@ return function (uri, callback)
 
         local functionName = source.parent[1]
 
+        --- don't apply rule if there is no @param or @return annotation yet
+        --- so comments and @async can be applied without the need for a full documentation
+        if(not findSignatureDoc(source.bindDocs)) then
+            return
+        end
+
         if source.args and #source.args > 0 then
             for _, arg in ipairs(source.args) do
                 local argName = arg[1]