address comments: simplify struct and field name retrieval; enhance documentation for dependency types

Author: yongruilin

pkg/analysis/dependenttags/analyzer.go

@@ -76,9 +76,9 @@ func (a *analyzer) run(pass *analysis.Pass) (any, error) {
 			if _, ok := fieldMarkers[rule.Identifier]; ok {
 				switch rule.Type {
 				case DependencyTypeAny:
-					handleAny(pass, field, rule, fieldMarkers)
+					handleAny(pass, field, rule, fieldMarkers, qualifiedFieldName)
 				case DependencyTypeAll:
-					handleAll(pass, field, rule, fieldMarkers)
+					handleAll(pass, field, rule, fieldMarkers, qualifiedFieldName)
 				default:
 					panic(fmt.Sprintf("unknown dependency type %s", rule.Type))
 				}
@@ -88,7 +88,7 @@ func (a *analyzer) run(pass *analysis.Pass) (any, error) {
 
 	return nil, nil //nolint:nilnil
 }
-func handleAll(pass *analysis.Pass, field *ast.Field, rule Rule, fieldMarkers markers.MarkerSet) {
+func handleAll(pass *analysis.Pass, field *ast.Field, rule Rule, fieldMarkers markers.MarkerSet, qualifiedFieldName string) {
 	missing := make([]string, 0, len(rule.Dependents))
 
 	for _, dependent := range rule.Dependents {
@@ -98,12 +98,11 @@ func handleAll(pass *analysis.Pass, field *ast.Field, rule Rule, fieldMarkers ma
 	}
 
 	if len(missing) > 0 {
-		structName, fieldName := utils.GetStructAndFieldName(pass, field)
-		pass.Reportf(field.Pos(), "field %s.%s with marker +%s is missing required marker(s): %s", structName, fieldName, rule.Identifier, strings.Join(missing, ", "))
+		pass.Reportf(field.Pos(), "field %s with marker +%s is missing required marker(s): %s", qualifiedFieldName, rule.Identifier, strings.Join(missing, ", "))
 	}
 }
 
-func handleAny(pass *analysis.Pass, field *ast.Field, rule Rule, fieldMarkers markers.MarkerSet) {
+func handleAny(pass *analysis.Pass, field *ast.Field, rule Rule, fieldMarkers markers.MarkerSet, qualifiedFieldName string) {
 	found := false
 
 	for _, dependent := range rule.Dependents {
@@ -119,7 +118,6 @@ func handleAny(pass *analysis.Pass, field *ast.Field, rule Rule, fieldMarkers ma
 			dependents[i] = fmt.Sprintf("+%s", d)
 		}
 
-		structName, fieldName := utils.GetStructAndFieldName(pass, field)
-		pass.Reportf(field.Pos(), "field %s.%s with marker +%s requires at least one of the following markers, but none were found: %s", structName, fieldName, rule.Identifier, strings.Join(dependents, ", "))
+		pass.Reportf(field.Pos(), "field %s with marker +%s requires at least one of the following markers, but none were found: %s", qualifiedFieldName, rule.Identifier, strings.Join(dependents, ", "))
 	}
 }

pkg/analysis/dependenttags/config.go

@@ -39,6 +39,7 @@ type Rule struct {
 	// Dependents are the markers that are required by Main.
 	Dependents []string `mapstructure:"dependents"`
 	// Type defines how to interpret the dependents list.
-	// Can be 'all' (default) or 'any'.
+	// When set to All, every dependent in the list must be present when the identifier is present on a field or type.
+	// When set to Any, at least one of the listed dependents must be present when the identifier is present on a field or type.
 	Type DependencyType `mapstructure:"type,omitempty"`
 }

pkg/analysis/dependenttags/doc.go

@@ -21,30 +21,30 @@ limitations under the License.
 // a set of other markers (dependent tags) are also present. This is useful for enforcing API
 // contracts where certain markers imply the presence of others.
 //
-// For example, a field marked with `+k-8s:unionMember` must also be marked with `+k8s:optional`.
+// For example, a field marked with `+k8s:unionMember` must also be marked with `+k8s:optional`.
 //
 // # Configuration
 //
 // The linter is configured with a list of rules. Each rule specifies an identifier marker and a list of
 // dependent markers. The `type` field is required and specifies how to interpret the dependents list:
-// - `all`: all dependent markers are required.
-// - `any`: at least one of the dependent markers is required.
+// - `All`: all dependent markers are required.
+// - `Any`: at least one of the dependent markers is required.
 //
 // This linter only checks for the presence or absence of markers; it does not inspect or enforce specific values within those markers. It also does not provide automatic fixes.
 //
 //	linters:
 //	  dependenttags:
 //	    rules:
 //	    - identifier: "k8s:unionMember"
-//	      type: "all"
+//	      type: "All"
 //	      dependents:
 //	      - "k8s:optional"
 //	    - identifier: "listType"
-//	      type: "all"
+//	      type: "All"
 //	      dependents:
 //	      - "k8s:listType"
 //	    - identifier: "example:any"
-//	      type: "any"
+//	      type: "Any"
 //	      dependents:
 //	      - "dep1"
 //	      - "dep2"

pkg/analysis/utils/utils.go

@@ -491,11 +491,3 @@ func getFieldTypeName(field *ast.Field) string {
 
 	return ""
 }
-
-// GetStructAndFieldName returns the name of the struct and the field name for a given field.
-func GetStructAndFieldName(pass *analysis.Pass, field *ast.Field) (string, string) {
-	structName := GetStructNameForField(pass, field)
-	fieldName := FieldName(field)
-
-	return structName, fieldName
-}