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...)

2 files changed, 135 insertions, 15 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]
diff --git a/test/diagnostics/incomplete-signature-doc.lua b/test/diagnostics/incomplete-signature-doc.lua
index c3099cd2..6c529a62 100644
--- a/test/diagnostics/incomplete-signature-doc.lua
+++ b/test/diagnostics/incomplete-signature-doc.lua
@@ -25,7 +25,23 @@ config.set(nil, 'Lua.diagnostics.neededFileStatus',
     ['incomplete-signature-doc'] = 'Any!' -- override groupFileStatus
 })
 
--- check global functions
+-- -------------------------------------
+-- about the structure of these test cases
+--
+-- the following test cases are grouped by the number of parameters and return values of the functions
+-- so first global functions with: 
+-- no parameter and return value (FG), one parameter (FGP), two parameters (FGPP),
+-- one return value (FGR), two return values (FGRR) and parameter and return value (FGPR)
+-- after that, these groups are also done for local functions (FL, FLP, ...)
+--
+-- in these groups, different versions of documentation are tested:
+-- no comment, simple comment, @async annotation (which is no signature doc),
+-- incomplete signature doc (only part of the necessary @param or @return annotations, if possible) - the only cases that should generating warnings
+-- and complete signature docs (all necessary @param and @return annotations)
+-- -------------------------------------
+
+-- global functions no parameter, no return value
+-- no incomplete signature docs possible
 TEST [[
 function FG0()
 end
@@ -33,15 +49,26 @@ end
 ---comment
 function FG1()
 end
+
+---@async
+function FG1_()
+end
 ]]
 
+-- global functions with single parameter, no return value
+-- no incomplete signature docs possible
 TEST [[
 function FGP0(p)
   print(p)
 end
 
 ---comment
-function FGP1(<!p!>)
+function FGP1(p)
+  print(p)
+end
+
+---@async
+function FGP1_(p)
   print(p)
 end
 
@@ -52,13 +79,20 @@ function FGP2(p)
 end
 ]]
 
+-- global functions with two parameters, no return value
+-- incomplete signature docs when exactly one of the parameters is documented
 TEST [[
 function FGPP0(p0, p1)
   print(p0, p1)
 end
 
 ---comment
-function FGPP1(<!p0!>, <!p1!>)
+function FGPP1(p0, p1)
+  print(p0, p1)
+end
+
+---@async
+function FGPP1_(p0, p1)
   print(p0, p1)
 end
 
@@ -69,6 +103,12 @@ function FGPP2(p0, <!p1!>)
 end
 
 ---comment
+---@param p1 any
+function FGPP2_(<!p0!>, p1)
+  print(p0, p1)
+end
+
+---comment
 ---@param p0 any
 ---@param p1 any
 function FGPP3(p0, p1)
@@ -76,6 +116,8 @@ function FGPP3(p0, p1)
 end
 ]]
 
+-- global functions with no parameter, single return value
+-- no incomplete signature docs possible
 TEST [[
 function FGR0()
   return 0
@@ -83,7 +125,12 @@ end
 
 ---comment
 function FGR1()
-  return <!0!>
+  return 0
+end
+
+---@async
+function FGR1_()
+  return 0
 end
 
 ---comment
@@ -93,6 +140,8 @@ function FGR2()
 end
 ]]
 
+-- global functions with no parameter, two return values
+-- incomplete signature docs when exactly one of the return values is documented
 TEST [[
 function FGRR0()
   return 0, 1
@@ -100,7 +149,12 @@ end
 
 ---comment
 function FGRR1()
-  return <!0!>, <!1!>
+  return 0, 1
+end
+
+---@async
+function FGRR1_()
+  return 0, 1
 end
 
 ---comment
@@ -117,6 +171,8 @@ function FGRR3()
 end
 ]]
 
+-- global functions with one parameter, one return value
+-- incomplete signature docs when exactly one of parameter or return value is documented
 TEST [[
 function FGPR0(p)
   print(p)
@@ -124,9 +180,15 @@ function FGPR0(p)
 end
 
 ---comment
-function FGPR1(<!p!>)
+function FGPR1(p)
   print(p)
-  return <!0!>
+  return 0
+end
+
+---@async
+function FGPR1_(p)
+  print(p)
+  return 0
 end
 
 ---comment
@@ -152,8 +214,8 @@ function FGPR4(p)
 end
 ]]
 
--- check local functions
-
+-- local functions with no parameter, no return value
+-- no incomplete signature docs possible
 TEST [[
 local function FL0()
 end
@@ -165,8 +227,13 @@ local function FL1()
 end
 
 FL1()
+
+---@async
+local function FL1_()
 ]]
 
+-- local functions with single parameter, no return value
+-- no incomplete signature docs possible
 TEST [[
 local function FLP0(p)
   print(p)
@@ -175,12 +242,17 @@ end
 FLP0(0)
 
 ---comment
-local function FLP1(<!p!>)
+local function FLP1(p)
   print(p)
 end
 
 FLP1(0)
 
+---@async
+local function FLP1_(p)
+  print(p)
+end
+
 ---comment
 ---@param p any
 local function FLP2(p)
@@ -190,6 +262,8 @@ end
 FLP2(0)
 ]]
 
+-- local functions with two parameters, no return value
+-- incomplete signature docs when exactly one of the parameters is documented
 TEST [[
 local function FLPP0(p0, p1)
   print(p0, p1)
@@ -198,12 +272,17 @@ end
 FLPP0(0, 1)
 
 ---comment
-local function FLPP1(<!p0!>, <!p1!>)
+local function FLPP1(p0, p1)
   print(p0, p1)
 end
 
 FLPP1(0, 1)
 
+---@async
+local function FLPP1_(p0, p1)
+  print(p0, p1)
+end
+
 ---comment
 ---@param p0 any
 local function FLPP2(p0, <!p1!>)
@@ -222,6 +301,8 @@ end
 FLPP3(0, 1)
 ]]
 
+-- local functions with no parameter, single return value
+-- no incomplete signature docs possible
 TEST [[
 local function FLR0()
   return 0
@@ -231,7 +312,12 @@ local vr0 = FLR0()
 
 ---comment
 local function FLR1()
-  return <!0!>
+  return 0
+end
+
+---@async
+local function FLR1_()
+  return 0
 end
 
 local vr1 = FLR1()
@@ -245,6 +331,8 @@ end
 local vr2 = FLR2()
 ]]
 
+-- local functions with no parameter, two return values
+-- incomplete signature docs when exactly one of the return values is documented
 TEST [[
 local function FLRR0()
   return 0, 1
@@ -254,11 +342,16 @@ local vrr0, _ = FLRR0()
 
 ---comment
 local function FLRR1()
-  return <!0!>, <!1!>
+  return 0, 1
 end
 
 local vrr1, _ = FLRR1()
 
+---@async
+local function FLRR1_()
+  return 0, 1
+end
+
 ---comment
 ---@return integer
 local function FLRR2()
@@ -277,6 +370,8 @@ end
 local vrr3, _ = FLRR3()
 ]]
 
+-- local functions with one parameter, one return value
+-- incomplete signature docs when exactly one of parameter or return value is documented
 TEST [[
 local function FLPR0(p)
   print(p)
@@ -286,9 +381,15 @@ end
 local vpr0 = FLPR0(0)
 
 ---comment
-local function FLPR1(<!p!>)
+local function FLPR1(p)
   print(p)
-  return <!0!>
+  return 0
+end
+
+---@async
+local function FLPR1_(p)
+  print(p)
+  return 0
 end
 
 local vpr1 = FLPR1(0)