From 8a884c3093b8b57011b35a1de650b6b2376c24e0 Mon Sep 17 00:00:00 2001 From: AndreaWalchshoferSCCH <122894794+AndreaWalchshoferSCCH@users.noreply.github.com> Date: Wed, 28 Jun 2023 12:12:33 +0200 Subject: 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...) --- test/diagnostics/incomplete-signature-doc.lua | 131 +++++++++++++++++++++++--- 1 file changed, 116 insertions(+), 15 deletions(-) (limited to 'test/diagnostics') 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() +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(, ) +function FGPP1(p0, p1) + print(p0, p1) +end + +---@async +function FGPP1_(p0, p1) print(p0, p1) end @@ -68,6 +102,12 @@ function FGPP2(p0, ) print(p0, p1) end +---comment +---@param p1 any +function FGPP2_(, p1) + print(p0, p1) +end + ---comment ---@param p0 any ---@param p1 any @@ -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 + 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 , + 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() +function FGPR1(p) print(p) - return + 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() +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(, ) +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, ) @@ -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 + 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 , + 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() +local function FLPR1(p) print(p) - return + return 0 +end + +---@async +local function FLPR1_(p) + print(p) + return 0 end local vpr1 = FLPR1(0) -- cgit v1.2.3