lint: fail on missing package comment (#3524)

golint does check for missing package comment, but with low confidence.
golint checks each file, and complains on every file missing package comment, even though another file in the same package has the comment.

This PR adds a golint check with low min_confidence, and filters out false-positives.

benchmark/worker/main.go

@@ -16,6 +16,8 @@
  *
  */
 
+// Binary worker implements the benchmark worker that can turn into a benchmark
+// client or server.
 package main
 
 import (

examples/features/health/client/main.go

@@ -16,6 +16,7 @@
  *
  */
 
+// Binary client is an example client.
 package main
 
 import (

examples/features/health/server/main.go

@@ -16,6 +16,7 @@
  *
  */
 
+// Binary server is an example server.
 package main
 
 import (

examples/helloworld/mock_helloworld/hw_mock.go

@@ -1,4 +1,4 @@
-// Automatically generated by MockGen. DO NOT EDIT!
+// Code generated by MockGen. DO NOT EDIT.
 // Source: google.golang.org/grpc/examples/helloworld/helloworld (interfaces: GreeterClient)
 
 package mock_helloworld

examples/route_guide/mock_routeguide/rg_mock.go

@@ -1,4 +1,4 @@
-// Automatically generated by MockGen. DO NOT EDIT!
+// Code generated by MockGen. DO NOT EDIT.
 // Source: google.golang.org/grpc/examples/route_guide/routeguide (interfaces: RouteGuideClient,RouteGuide_RouteChatClient)
 
 package mock_routeguide

internal/serviceconfig/serviceconfig.go

@@ -16,6 +16,7 @@
  *
  */
 
+// Package serviceconfig contains utility functions to parse service config.
 package serviceconfig
 
 import (

internal/wrr/wrr.go

@@ -15,6 +15,8 @@
  * limitations under the License.
  */
 
+// Package wrr contains the interface and common implementations of wrr
+// algorithms.
 package wrr
 
 // WRR defines an interface that implements weighted round robin.

interop/client/client.go

@@ -16,6 +16,7 @@
  *
  */
 
+// Binary client is an interop client.
 package main
 
 import (

interop/grpclb_fallback/client.go

@@ -20,6 +20,7 @@
  *
  */
 
+// Binary grpclb_fallback is an interop test client for grpclb fallback.
 package main
 
 import (

interop/http2/negative_http2_client.go

@@ -14,13 +14,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
- *
- * Client used to test http2 error edge cases like GOAWAYs and RST_STREAMs
- *
- * Documentation:
- *	 https://github.com/grpc/grpc/blob/master/doc/negative-http2-interop-test-descriptions.md
  */
 
+// Binary http2 is used to test http2 error edge cases like GOAWAYs and
+// RST_STREAMs
+//
+// Documentation:
+// https://github.com/grpc/grpc/blob/master/doc/negative-http2-interop-test-descriptions.md
 package main
 
 import (

interop/server/server.go

@@ -16,6 +16,7 @@
  *
  */
 
+// Binary server is an interop server.
 package main
 
 import (

interop/test_utils.go

@@ -18,6 +18,7 @@
 
 //go:generate protoc --go_out=plugins=grpc:. grpc_testing/test.proto
 
+// Package interop contains functions used by interop client/server.
 package interop
 
 import (

stress/metrics_client/main.go

@@ -16,6 +16,7 @@
  *
  */
 
+// Binary metrics_client is a client to retrieve metrics from the server.
 package main
 
 import (

test/servertester.go

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+// Package test contains tests.
 package test
 
 import (

vet.sh

@@ -163,4 +163,35 @@ naming.Watcher
 resolver.Backend
 resolver.GRPCLB' "${SC_OUT}"
 
+# - special golint on package comments.
+lint_package_comment_per_package() {
+  # Number of files in this go package.
+  fileCount=$(go list -f '{{len .GoFiles}}' $1)
+  if [ ${fileCount} -eq 0 ]; then
+    return 0
+  fi
+  # Number of package errors generated by golint.
+  lintPackageCommentErrorsCount=$(golint --min_confidence 0 $1 | grep -c "should have a package comment")
+  # golint complains about every file that's missing the package comment. If the
+  # number of files for this package is greater than the number of errors, there's
+  # at least one file with package comment, good. Otherwise, fail.
+  if [ ${fileCount} -le ${lintPackageCommentErrorsCount} ]; then
+    echo "Package $1 (with ${fileCount} files) is missing package comment"
+    return 1
+  fi
+}
+lint_package_comment() {
+  set +ex
+
+  count=0
+  for i in $(go list ./...); do
+    lint_package_comment_per_package "$i"
+    ((count += $?))
+  done
+
+  set -ex
+  return $count
+}
+lint_package_comment
+
 echo SUCCESS

xds/internal/internal.go

@@ -15,6 +15,8 @@
  * limitations under the License.
  */
 
+// Package internal contains functions/structs shared by xds
+// balancers/resolvers.
 package internal
 
 import (