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

3 files changed, 667 insertions, 0 deletions

diff --git a/test/diagnostics/incomplete-signature-doc.lua b/test/diagnostics/incomplete-signature-doc.lua
new file mode 100644
index 00000000..c3099cd2
--- /dev/null
+++ b/test/diagnostics/incomplete-signature-doc.lua
@@ -0,0 +1,331 @@
+local config = require 'config'
+local util   = require 'utility'
+
+-- disable all default groups to make isolated tests
+config.set(nil, 'Lua.diagnostics.groupFileStatus',
+{
+    ['ambiguity']     = 'None',
+    ['await']         = 'None',
+    ['codestyle']     = 'None',
+    ['conventions']   = 'None',
+    ['duplicate']     = 'None',
+    ['global']        = 'None',
+    ['luadoc']        = 'None',
+    ['redefined']     = 'None',
+    ['strict']        = 'None',
+    ['strong']        = 'None',
+    ['type-check']    = 'None',
+    ['unbalanced']    = 'None',
+    ['unused']        = 'None'
+})
+
+-- enable single diagnostic that is to be tested
+config.set(nil, 'Lua.diagnostics.neededFileStatus',
+{
+    ['incomplete-signature-doc'] = 'Any!' -- override groupFileStatus
+})
+
+-- check global functions
+TEST [[
+function FG0()
+end
+
+---comment
+function FG1()
+end
+]]
+
+TEST [[
+function FGP0(p)
+  print(p)
+end
+
+---comment
+function FGP1(<!p!>)
+  print(p)
+end
+
+---comment
+---@param p any
+function FGP2(p)
+  print(p)
+end
+]]
+
+TEST [[
+function FGPP0(p0, p1)
+  print(p0, p1)
+end
+
+---comment
+function FGPP1(<!p0!>, <!p1!>)
+  print(p0, p1)
+end
+
+---comment
+---@param p0 any
+function FGPP2(p0, <!p1!>)
+  print(p0, p1)
+end
+
+---comment
+---@param p0 any
+---@param p1 any
+function FGPP3(p0, p1)
+  print(p0, p1)
+end
+]]
+
+TEST [[
+function FGR0()
+  return 0
+end
+
+---comment
+function FGR1()
+  return <!0!>
+end
+
+---comment
+---@return integer
+function FGR2()
+  return 0
+end
+]]
+
+TEST [[
+function FGRR0()
+  return 0, 1
+end
+
+---comment
+function FGRR1()
+  return <!0!>, <!1!>
+end
+
+---comment
+---@return integer
+function FGRR2()
+  return 0, <!1!>
+end
+
+---comment
+---@return integer
+---@return integer
+function FGRR3()
+  return 0, 1
+end
+]]
+
+TEST [[
+function FGPR0(p)
+  print(p)
+  return 0
+end
+
+---comment
+function FGPR1(<!p!>)
+  print(p)
+  return <!0!>
+end
+
+---comment
+---@param p any
+function FGPR2(p)
+  print(p)
+  return <!0!>
+end
+
+---comment
+---@return integer
+function FGPR3(<!p!>)
+  print(p)
+  return 0
+end
+
+---comment
+---@param p any
+---@return integer
+function FGPR4(p)
+  print(p)
+  return 0
+end
+]]
+
+-- check local functions
+
+TEST [[
+local function FL0()
+end
+
+FL0()
+
+---comment
+local function FL1()
+end
+
+FL1()
+]]
+
+TEST [[
+local function FLP0(p)
+  print(p)
+end
+
+FLP0(0)
+
+---comment
+local function FLP1(<!p!>)
+  print(p)
+end
+
+FLP1(0)
+
+---comment
+---@param p any
+local function FLP2(p)
+  print(p)
+end
+
+FLP2(0)
+]]
+
+TEST [[
+local function FLPP0(p0, p1)
+  print(p0, p1)
+end
+
+FLPP0(0, 1)
+
+---comment
+local function FLPP1(<!p0!>, <!p1!>)
+  print(p0, p1)
+end
+
+FLPP1(0, 1)
+
+---comment
+---@param p0 any
+local function FLPP2(p0, <!p1!>)
+  print(p0, p1)
+end
+
+FLPP2(0, 1)
+
+---comment
+---@param p0 any
+---@param p1 any
+local function FLPP3(p0, p1)
+  print(p0, p1)
+end
+
+FLPP3(0, 1)
+]]
+
+TEST [[
+local function FLR0()
+  return 0
+end
+
+local vr0 = FLR0()
+
+---comment
+local function FLR1()
+  return <!0!>
+end
+
+local vr1 = FLR1()
+
+---comment
+---@return integer
+local function FLR2()
+  return 0
+end
+
+local vr2 = FLR2()
+]]
+
+TEST [[
+local function FLRR0()
+  return 0, 1
+end
+
+local vrr0, _ = FLRR0()
+
+---comment
+local function FLRR1()
+  return <!0!>, <!1!>
+end
+
+local vrr1, _ = FLRR1()
+
+---comment
+---@return integer
+local function FLRR2()
+  return 0, <!1!>
+end
+
+local vrr2, _ = FLRR2()
+
+---comment
+---@return integer
+---@return integer
+local function FLRR3()
+  return 0, 1
+end
+
+local vrr3, _ = FLRR3()
+]]
+
+TEST [[
+local function FLPR0(p)
+  print(p)
+  return 0
+end
+
+local vpr0 = FLPR0(0)
+
+---comment
+local function FLPR1(<!p!>)
+  print(p)
+  return <!0!>
+end
+
+local vpr1 = FLPR1(0)
+
+---comment
+---@param p any
+local function FLPR2(p)
+  print(p)
+  return <!0!>
+end
+
+local vpr2 = FLPR2(0)
+
+---comment
+---@return integer
+local function FLPR3(<!p!>)
+  print(p)
+  return 0
+end
+
+local vpr3 = FLPR3(0)
+
+---comment
+---@param p any
+---@return integer
+local function FLPR4(p)
+  print(p)
+  return 0
+end
+
+local vpr4 = FLPR4(0)
+]]
+
+-- reset configurations
+config.set(nil, 'Lua.diagnostics.groupFileStatus',
+{})
+config.set(nil, 'Lua.diagnostics.neededFileStatus',
+{})
+config.set(nil, 'Lua.diagnostics.globals',
+{})
\ No newline at end of file
diff --git a/test/diagnostics/init.lua b/test/diagnostics/init.lua
index 5e8abf7d..821685f0 100644
--- a/test/diagnostics/init.lua
+++ b/test/diagnostics/init.lua
@@ -86,5 +86,8 @@ end
 
 require 'diagnostics.common'
 require 'diagnostics.type-check'
+require 'diagnostics.incomplete-signature-doc'
+require 'diagnostics.missing-global-doc'
 require 'diagnostics.global-element'
 require 'diagnostics.uppercase-local'
+
diff --git a/test/diagnostics/missing-global-doc.lua b/test/diagnostics/missing-global-doc.lua
new file mode 100644
index 00000000..2ebc237a
--- /dev/null
+++ b/test/diagnostics/missing-global-doc.lua
@@ -0,0 +1,333 @@
+local config = require 'config'
+local util   = require 'utility'
+
+-- disable all default groups to make isolated tests
+config.set(nil, 'Lua.diagnostics.groupFileStatus',
+{
+    ['ambiguity']     = 'None',
+    ['await']         = 'None',
+    ['codestyle']     = 'None',
+    ['conventions']   = 'None',
+    ['duplicate']     = 'None',
+    ['global']        = 'None',
+    ['luadoc']        = 'None',
+    ['redefined']     = 'None',
+    ['strict']        = 'None',
+    ['strong']        = 'None',
+    ['type-check']    = 'None',
+    ['unbalanced']    = 'None',
+    ['unused']        = 'None'
+})
+
+-- enable single diagnostic that is to be tested
+config.set(nil, 'Lua.diagnostics.neededFileStatus',
+{
+    ['missing-global-doc'] = 'Any!' -- override groupFileStatus
+})
+
+
+-- check global functions
+TEST [[
+<!function FG0()
+end!>
+
+---comment
+function FG1()
+end
+]]
+
+TEST [[
+function FGP0(<!p!>)
+  print(p)
+end
+
+---comment
+function FGP1(<!p!>)
+  print(p)
+end
+
+---comment
+---@param p any
+function FGP2(p)
+  print(p)
+end
+]]
+
+TEST [[
+function FGPP0(<!p0!>, <!p1!>)
+  print(p0, p1)
+end
+
+---comment
+function FGPP1(<!p0!>, <!p1!>)
+  print(p0, p1)
+end
+
+---comment
+---@param p0 any
+function FGPP2(p0, <!p1!>)
+  print(p0, p1)
+end
+
+---comment
+---@param p0 any
+---@param p1 any
+function FGPP3(p0, p1)
+  print(p0, p1)
+end
+]]
+
+TEST [[
+function FGR0()
+  return <!0!>
+end
+
+---comment
+function FGR1()
+  return <!0!>
+end
+
+---comment
+---@return integer
+function FGR2()
+  return 0
+end
+]]
+
+TEST [[
+function FGRR0()
+  return <!0!>, <!1!>
+end
+
+---comment
+function FGRR1()
+  return <!0!>, <!1!>
+end
+
+---comment
+---@return integer
+function FGRR2()
+  return 0, <!1!>
+end
+
+---comment
+---@return integer
+---@return integer
+function FGRR3()
+  return 0, 1
+end
+]]
+
+
+TEST [[
+function FGPR0(<!p!>)
+  print(p)
+  return <!0!>
+end
+
+---comment
+function FGPR1(<!p!>)
+  print(p)
+  return <!0!>
+end
+
+---comment
+---@param p any
+function FGPR2(p)
+  print(p)
+  return <!0!>
+end
+
+---comment
+---@return integer
+function FGPR3(<!p!>)
+  print(p)
+  return 0
+end
+
+---comment
+---@param p any
+---@return integer
+function FGPR4(p)
+  print(p)
+  return 0
+end
+]]
+
+-- check local functions
+
+TEST [[
+local function FL0()
+end
+
+FL0()
+
+---comment
+local function FL1()
+end
+
+FL1()
+]]
+
+TEST [[
+local function FLP0(p)
+  print(p)
+end
+
+FLP0(0)
+
+---comment
+local function FLP1(p)
+  print(p)
+end
+
+FLP1(0)
+
+---comment
+---@param p any
+local function FLP2(p)
+  print(p)
+end
+
+FLP2(0)
+]]
+
+TEST [[
+local function FLPP0(p0, p1)
+  print(p0, p1)
+end
+
+FLPP0(0, 1)
+
+---comment
+local function FLPP1(p0, p1)
+  print(p0, p1)
+end
+
+FLPP1(0, 1)
+
+---comment
+---@param p0 any
+local function FLPP2(p0, p1)
+  print(p0, p1)
+end
+
+FLPP2(0, 1)
+
+---comment
+---@param p0 any
+---@param p1 any
+local function FLPP3(p0, p1)
+  print(p0, p1)
+end
+
+FLPP3(0, 1)
+]]
+
+TEST [[
+local function FLR0()
+  return 0
+end
+
+local vr0 = FLR0()
+
+---comment
+local function FLR1()
+  return 0
+end
+
+local vr1 = FLR1()
+
+---comment
+---@return integer
+local function FLR2()
+  return 0
+end
+
+local vr2 = FLR2()
+]]
+
+TEST [[
+local function FLRR0()
+  return 0, 1
+end
+
+local vrr0, _ = FLRR0()
+
+---comment
+local function FLRR1()
+  return 0, 1
+end
+
+local vrr1, _ = FLRR1()
+
+---comment
+---@return integer
+local function FLRR2()
+  return 0, 1
+end
+
+local vrr2, _ = FLRR2()
+
+---comment
+---@return integer
+---@return integer
+local function FLRR3()
+  return 0, 1
+end
+
+local vrr3, _ = FLRR3()
+]]
+
+TEST [[
+local function FLPR0(p)
+  print(p)
+  return 0
+end
+
+local vpr0 = FLPR0(0)
+
+---comment
+local function FLPR1(p)
+  print(p)
+  return 0
+end
+
+local vpr1 = FLPR1(0)
+
+---comment
+---@param p any
+local function FLPR2(p)
+  print(p)
+  return 0
+end
+
+local vpr2 = FLPR2(0)
+
+---comment
+---@return integer
+local function FLPR3(p)
+  print(p)
+  return 0
+end
+
+local vpr3 = FLPR3(0)
+
+---comment
+---@param p any
+---@return integer
+local function FLPR4(p)
+  print(p)
+  return 0
+end
+
+local vpr4 = FLPR4(0)
+]]
+
+-- reset configurations
+config.set(nil, 'Lua.diagnostics.groupFileStatus',
+{})
+config.set(nil, 'Lua.diagnostics.neededFileStatus',
+{})
+config.set(nil, 'Lua.diagnostics.globals',
+{})
\ No newline at end of file