list: tidy the doc comments and tests (#1162)

Author: bbasata

list/list_resource.go

@@ -85,35 +85,39 @@ type ListResourceWithValidateConfig interface {
 	ValidateListResourceConfig(context.Context, ValidateConfigRequest, *ValidateConfigResponse)
 }
 
-// ListRequest represents a request for the provider to list instances
-// of a managed resource type that satisfy a user-defined request. An instance
-// of this reqeuest struct is passed as an argument to the provider's
-// ListResource function implementation.
+// ListRequest represents a request for the provider to list instances of a
+// managed resource type that satisfy a user-defined request. An instance of
+// this reqeuest struct is passed as an argument to the provider's List
+// function implementation.
 type ListRequest struct {
 	// Config is the configuration the user supplied for listing resource
 	// instances.
 	Config tfsdk.Config
 
 	// IncludeResource indicates whether the provider should populate the
-	// Resource field in the ListResult struct.
+	// [ListResult.Resource] field.
 	IncludeResource bool
 }
 
-// ListResultsStream represents a streaming response to a ListRequest.
-// An instance of this struct is supplied as an argument to the provider's
-// ListResource function implementation function. The provider should set a Results
-// iterator function that yields zero or more results of type ListResult.
+// ListResultsStream represents a streaming response to a [ListRequest].  An
+// instance of this struct is supplied as an argument to the provider's
+// [ListResource.List] function. The provider should set a Results iterator
+// function that pushes zero or more results of type [ListResult].
 //
 // For convenience, a provider implementation may choose to convert a slice of
 // results into an iterator using [slices.Values].
-//
-// [slices.Values]: https://pkg.go.dev/slices#Values
 type ListResultsStream struct {
-	// Results is a function that emits ListResult values via its yield
+	// Results is a function that emits [ListResult] values via its push
 	// function argument.
+	//
+	// To indicate a fatal processing error, push a [ListResult] that contains
+	// a [diag.ErrorDiagnostic].
 	Results iter.Seq[ListResult]
 }
 
+// NoListResults is an iterator that pushes zero results.
+var NoListResults = func(func(ListResult) bool) {}
+
 // ListResult represents a listed managed resource instance.
 type ListResult struct {
 	// Identity is the identity of the managed resource instance.
@@ -124,7 +128,7 @@ type ListResult struct {
 	// Resource is the provider's representation of the attributes of the
 	// listed managed resource instance.
 	//
-	// If ListRequest.IncludeResource is true, a nil value will raise
+	// If [ListRequest.IncludeResource] is true, a nil value will raise
 	// a warning diagnostic.
 	Resource *tfsdk.Resource
 
@@ -140,8 +144,8 @@ type ListResult struct {
 
 // ValidateConfigRequest represents a request to validate the configuration of
 // a list resource. An instance of this request struct is supplied as an
-// argument to the ValidateListResourceConfig receiver method or automatically
-// passed through to each ListResourceConfigValidator.
+// argument to the [ListResourceWithValidateConfig.ValidateListResourceConfig]
+// receiver method or automatically passed through to each [ConfigValidator].
 type ValidateConfigRequest struct {
 	// Config is the configuration the user supplied for the resource.
 	//
@@ -151,10 +155,10 @@ type ValidateConfigRequest struct {
 	Config tfsdk.Config
 }
 
-// ValidateConfigResponse represents a response to a ValidateConfigRequest. An
-// instance of this response struct is supplied as an argument to the
-// list.ValidateListResourceConfig receiver method or automatically passed
-// through to each ConfigValidator.
+// ValidateConfigResponse represents a response to a [ValidateConfigRequest].
+// An instance of this response struct is supplied as an argument to the
+// [list.ValidateListResourceConfig] receiver method or automatically passed
+// through to each [ConfigValidator].
 type ValidateConfigResponse struct {
 	// Diagnostics report errors or warnings related to validating the list
 	// configuration. An empty slice indicates success, with no warnings

list/schema/schema.go

@@ -17,9 +17,8 @@ import (
 // Schema must satify the fwschema.Schema interface.
 var _ fwschema.Schema = Schema{}
 
-// Schema defines the structure and value types of resource data. This type
-// is used as the resource.SchemaResponse type Schema field, which is
-// implemented by the resource.DataSource type Schema method.
+// Schema defines the structure and value types of a list block. This is
+// returned as a ListResourceSchemas map value by the GetProviderSchemas RPC.
 type Schema struct {
 	// Attributes is the mapping of underlying attribute names to attribute
 	// definitions.
@@ -106,7 +105,7 @@ func (s Schema) GetMarkdownDescription() string {
 	return s.MarkdownDescription
 }
 
-// GetVersion returns zero because list resource schemas do not have a version.
+// GetVersion always returns 0 because list resource schemas cannot be versioned.
 func (s Schema) GetVersion() int64 {
 	return 0
 }
@@ -126,13 +125,6 @@ func (s Schema) TypeAtTerraformPath(ctx context.Context, p *tftypes.AttributePat
 	return fwschema.SchemaTypeAtTerraformPath(ctx, s, p)
 }
 
-// Validate verifies that the schema is not using a reserved field name for a top-level attribute.
-//
-// Deprecated: Use the ValidateImplementation method instead.
-func (s Schema) Validate() diag.Diagnostics {
-	return s.ValidateImplementation(context.Background())
-}
-
 // ValidateImplementation contains logic for validating the provider-defined
 // implementation of the schema and underlying attributes and blocks to prevent
 // unexpected errors or panics. This logic runs during the

list/schema/schema_test.go

@@ -797,47 +797,6 @@ func TestSchemaTypeAtTerraformPath(t *testing.T) {
 	}
 }
 
-func TestSchemaValidate(t *testing.T) {
-	t.Parallel()
-
-	testCases := map[string]struct {
-		schema        schema.Schema
-		expectedDiags diag.Diagnostics
-	}{
-		"empty-schema": {
-			schema: schema.Schema{},
-		},
-		"validate-implementation-error": {
-			schema: schema.Schema{
-				Attributes: map[string]schema.Attribute{
-					"depends_on": schema.StringAttribute{},
-				},
-			},
-			expectedDiags: diag.Diagnostics{
-				diag.NewErrorDiagnostic(
-					"Reserved Root Attribute/Block Name",
-					"When validating the resource or data source schema, an implementation issue was found. "+
-						"This is always an issue with the provider and should be reported to the provider developers.\n\n"+
-						"\"depends_on\" is a reserved root attribute/block name. "+
-						"This is to prevent practitioners from needing special Terraform configuration syntax.",
-				),
-			},
-		},
-	}
-
-	for name, testCase := range testCases {
-		t.Run(name, func(t *testing.T) {
-			t.Parallel()
-
-			diags := testCase.schema.Validate()
-
-			if diff := cmp.Diff(diags, testCase.expectedDiags); diff != "" {
-				t.Errorf("Unexpected diagnostics (+wanted, -got): %s", diff)
-			}
-		})
-	}
-}
-
 func TestSchemaValidateImplementation(t *testing.T) {
 	t.Parallel()