Compress multiple 'not documented' warnings into one warning (#544)

warn/warn_docstring.go

@@ -2,9 +2,10 @@ package warn
 
 import (
 	"fmt"
-	"github.com/bazelbuild/buildtools/build"
 	"regexp"
 	"strings"
+
+	"github.com/bazelbuild/buildtools/build"
 )
 
 // FunctionLengthDocstringThreshold is a limit for a function size (in statements), above which
@@ -244,13 +245,25 @@ func functionDocstringWarning(f *build.File, fix bool) []*Finding {
 		if isDocstringRequired || len(info.args) > 0 {
 
 			// Check whether all arguments are documented.
+			notDocumentedArguments := []string{}
 			paramNames := make(map[string]bool)
 			for _, param := range def.Params {
 				name := getParamName(param)
 				paramNames[name] = true
 				if _, ok := info.args[name]; !ok {
+					notDocumentedArguments = append(notDocumentedArguments, name)
+				}
+			}
+			if len(notDocumentedArguments) > 0 {
+				if len(notDocumentedArguments) == 1 {
+					findings = append(findings, makeFinding(f, start, end, "function-docstring",
+						fmt.Sprintf(`Argument "%s" is not documented.`, notDocumentedArguments[0]), true, nil))
+				} else {
 					findings = append(findings, makeFinding(f, start, end, "function-docstring",
-						fmt.Sprintf(`Argument "%s" is not documented.`, name), true, nil))
+						fmt.Sprintf(
+							`Arguments "%s" are not documented.`,
+							strings.Join(notDocumentedArguments, `", "`),
+						), true, nil))
 				}
 			}
 

warn/warn_docstring_test.go

@@ -259,11 +259,7 @@ def f(x, y, z = None, *args, **kwargs):
    pass
 `,
 		[]string{
-			`2: Argument "x" is not documented.`,
-			`2: Argument "y" is not documented.`,
-			`2: Argument "z" is not documented.`,
-			`2: Argument "*args" is not documented.`,
-			`2: Argument "**kwargs" is not documented.`,
+			`2: Arguments "x", "y", "z", "*args", "**kwargs" are not documented.`,
 		},
 		scopeEverywhere)