#1002 - add "checkPublicInterface" option to "exported" rule to allow check documentation on public methods on public interfaces

RULES_DESCRIPTIONS.md

@@ -14,7 +14,7 @@ List of all available rules.
   - [call-to-gc](#call-to-gc)
   - [cognitive-complexity](#cognitive-complexity)
   - [comment-spacings](#comment-spacings)
-  - [comments-density](#comment-spacings)
+  - [comments-density](#comments-density)
   - [confusing-naming](#confusing-naming)
   - [confusing-results](#confusing-results)
   - [constant-logical-expr](#constant-logical-expr)
@@ -474,12 +474,13 @@ Available flags are:
 * _checkPrivateReceivers_ enables checking public methods of private types
 * _disableStutteringCheck_ disables checking for method names that stutter with the package name (i.e. avoid failure messages of the form _type name will be used as x.XY by other packages, and that stutters; consider calling this Y_)
 * _sayRepetitiveInsteadOfStutters_ replaces the use of the term _stutters_ by _repetitive_ in failure messages
+* _checkPublicInterface_ enabled checking public method definitions in public interface types
 
 Example:
 
 ```toml
 [rule.exported]
-  arguments = ["checkPrivateReceivers", "disableStutteringCheck"]
+  arguments = ["checkPrivateReceivers", "disableStutteringCheck", "checkPublicInterface"]
 ```
 
 ## file-header

rule/exported.go

@@ -18,6 +18,7 @@ type ExportedRule struct {
 	configured             bool
 	checkPrivateReceivers  bool
 	disableStutteringCheck bool
+	checkPublicInterface   bool
 	stuttersMsg            string
 	sync.Mutex
 }
@@ -26,7 +27,12 @@ func (r *ExportedRule) configure(arguments lint.Arguments) {
 	r.Lock()
 	if !r.configured {
 		var sayRepetitiveInsteadOfStutters bool
-		r.checkPrivateReceivers, r.disableStutteringCheck, sayRepetitiveInsteadOfStutters = r.getConf(arguments)
+
+		r.checkPrivateReceivers,
+			r.disableStutteringCheck,
+			sayRepetitiveInsteadOfStutters,
+			r.checkPublicInterface = r.getConf(arguments)
+
 		r.stuttersMsg = "stutters"
 		if sayRepetitiveInsteadOfStutters {
 			r.stuttersMsg = "is repetitive"
@@ -57,6 +63,7 @@ func (r *ExportedRule) Apply(file *lint.File, args lint.Arguments) []lint.Failur
 		genDeclMissingComments: make(map[*ast.GenDecl]bool),
 		checkPrivateReceivers:  r.checkPrivateReceivers,
 		disableStutteringCheck: r.disableStutteringCheck,
+		checkPublicInterface:   r.checkPublicInterface,
 		stuttersMsg:            r.stuttersMsg,
 	}
 
@@ -70,7 +77,12 @@ func (*ExportedRule) Name() string {
 	return "exported"
 }
 
-func (r *ExportedRule) getConf(args lint.Arguments) (checkPrivateReceivers, disableStutteringCheck, sayRepetitiveInsteadOfStutters bool) {
+func (r *ExportedRule) getConf(args lint.Arguments) (
+	checkPrivateReceivers,
+	disableStutteringCheck,
+	sayRepetitiveInsteadOfStutters bool,
+	checkPublicInterface bool,
+) {
 	// if any, we expect a slice of strings as configuration
 	if len(args) < 1 {
 		return
@@ -88,6 +100,8 @@ func (r *ExportedRule) getConf(args lint.Arguments) (checkPrivateReceivers, disa
 			disableStutteringCheck = true
 		case "sayRepetitiveInsteadOfStutters":
 			sayRepetitiveInsteadOfStutters = true
+		case "checkPublicInterface":
+			checkPublicInterface = true
 		default:
 			panic(fmt.Sprintf("Unknown configuration flag %s for %s rule", flagStr, r.Name()))
 		}
@@ -104,6 +118,7 @@ type lintExported struct {
 	onFailure              func(lint.Failure)
 	checkPrivateReceivers  bool
 	disableStutteringCheck bool
+	checkPublicInterface   bool
 	stuttersMsg            string
 }
 
@@ -330,11 +345,54 @@ func (w *lintExported) Visit(n ast.Node) ast.Visitor {
 		}
 		w.lintTypeDoc(v, doc)
 		w.checkStutter(v.Name, "type")
-		// Don't proceed inside types.
+
+		if w.checkPublicInterface {
+			if iface, ok := v.Type.(*ast.InterfaceType); ok {
+				if ast.IsExported(v.Name.Name) {
+					w.doCheckPublicInterface(v.Name.Name, iface)
+				}
+			}
+		}
+
 		return nil
 	case *ast.ValueSpec:
 		w.lintValueSpecDoc(v, w.lastGen, w.genDeclMissingComments)
 		return nil
 	}
 	return w
 }
+
+func (w *lintExported) doCheckPublicInterface(typeName string, iface *ast.InterfaceType) {
+	for _, m := range iface.Methods.List {
+		// case of ast.Ident and other implicit fields
+		if len(m.Names) == 0 {
+			continue
+		}
+		if ast.IsExported(m.Names[0].Name) {
+			w.lintInterfaceMethod(typeName, m)
+		}
+	}
+}
+
+func (w *lintExported) lintInterfaceMethod(typeName string, m *ast.Field) {
+	name := m.Names[0].Name
+	if m.Doc == nil {
+		w.onFailure(lint.Failure{
+			Node:       m,
+			Confidence: 1,
+			Category:   "comments",
+			Failure:    fmt.Sprintf("public interface method %s.%s should be commented", typeName, name),
+		})
+		return
+	}
+	s := normalizeText(m.Doc.Text())
+	prefix := m.Names[0].Name + " "
+	if !strings.HasPrefix(s, prefix) {
+		w.onFailure(lint.Failure{
+			Node:       m.Doc,
+			Confidence: 0.8,
+			Category:   "comments",
+			Failure:    fmt.Sprintf(`comment on exported interface method %s.%s should be of the form "%s..."`, typeName, name, prefix),
+		})
+	}
+}

test/exported_test.go

@@ -24,3 +24,9 @@ func TestExportedReplacingStuttersByRepetitive(t *testing.T) {
 
 	testRule(t, "exported-issue-519", &rule.ExportedRule{}, &lint.RuleConfig{Arguments: args})
 }
+
+func TestCheckPublicInterfaceOption(t *testing.T) {
+	args := []any{"checkPublicInterface"}
+
+	testRule(t, "exported-issue-1002", &rule.ExportedRule{}, &lint.RuleConfig{Arguments: args})
+}

testdata/exported-issue-1002.go

@@ -0,0 +1,24 @@
+// Package golint comment
+package golint
+
+// by default code bellow is valid,
+// but if checkPublicInterface is switched on - it should check documentation in interfaces
+
+// Some - some interface
+type Some interface {
+	Other // should not fail
+	// Correct - should do all correct
+	Correct()
+	// MATCH /comment on exported interface method Some.SemiCorrect should be of the form "SemiCorrect ..."/
+	SemiCorrect() 
+	NonCorrect() // MATCH /public interface method Some.NonCorrect should be commented/
+}
+
+// Other - just to check names compatibility
+type Other interface {}
+
+// for private interfaces it doesn't check docs anyway
+
+type somePrivate interface {
+	AllGood()
+}