improve documentation around diagnostics and context aware methods

Author: appilon

diag/diagnostic.go

@@ -45,24 +45,33 @@ type Diagnostic struct {
 	// Severity indicates the level of the Diagnostic. Currently can be set to
 	// either Error or Warning
 	Severity Severity
+
 	// Summary is a short description of the problem, rendered above location
 	// information
 	Summary string
+
 	// Detail is an optional second message rendered below location information
 	// typically used to communicate a potential fix to the user.
 	Detail string
+
 	// AttributePath is a representation of the path starting from the root of
 	// block (resource, datasource, provider) under evaluation by the SDK, to
-	// the attribute that the Diagnostic should be associated to.
+	// the attribute that the Diagnostic should be associated to. Terraform will
+	// use this information to render information on where the problem took
+	// place in the user's configuration.
 	//
-	// It is represented with cty.Path, the SDK currently only supports path
-	// steps of either cty.GetAttrStep (an actual attribute) or cty.IndexStep
-	// (a step with Key of cty.StringVal for map indexes, and cty.NumberVal
-	// list indexes, pathing into sets is not currently supported). Please see
-	// go-cty documentation for more information.
+	// It is represented with cty.Path, which is a list of steps of either
+	// cty.GetAttrStep (an actual attribute) or cty.IndexStep (a step with Key
+	// of cty.StringVal for map indexes, and cty.NumberVal for list indexes).
 	//
-	// Terraform will use this information to render information on where the
-	// problem took place in the user's configuration.
+	// PLEASE NOTE: While cty can support indexing into sets, the SDK and
+	// protocol currently do not. For any Diagnostic related to a schema.TypeSet
+	// or a child of that type, please terminate the path at the schema.TypeSet
+	// and opt for more verbose Summary and Detail to help guide the user.
+	//
+	// Validity of the AttributePath is currently the responsibility of the
+	// developer, Terraform should render the root block (provider, resource,
+	// datasource) in cases where the attribute path is invalid.
 	AttributePath cty.Path
 }
 
@@ -93,10 +102,6 @@ func FromErr(err error) Diagnostic {
 }
 
 // Severity is an enum type marking the severity level of a Diagnostic
-//
-// Valid levels are
-// - Error
-// - Warning
 type Severity int
 
 const (

helper/schema/provider.go

@@ -59,7 +59,9 @@ type Provider struct {
 	ConfigureFunc ConfigureFunc
 
 	// ConfigureContextFunc is a function for configuring the provider. If the
-	// provider doesn't need to be configured, this can be omitted.
+	// provider doesn't need to be configured, this can be omitted. This function
+	// receives a context.Context that will cancel when Terraform sends a
+	// cancellation signal. This function can yield Diagnostics
 	ConfigureContextFunc ConfigureContextFunc
 
 	meta interface{}
@@ -232,8 +234,6 @@ func (p *Provider) ValidateResource(
 // given. This is useful for setting things like access keys.
 //
 // This won't be called at all if no provider configuration is given.
-//
-// Configure returns Diagnostics.
 func (p *Provider) Configure(ctx context.Context, c *terraform.ResourceConfig) diag.Diagnostics {
 
 	var diags diag.Diagnostics

helper/schema/resource.go

@@ -129,8 +129,15 @@ type Resource struct {
 	// a ConfigureFunc, this will be nil. This parameter should be used
 	// to store API clients, configuration structures, etc.
 	//
-	// If any errors occur during each of the operation, an error should be
-	// returned.
+	// These functions are passed a context configured to timeout with whatever
+	// was set as the timeout for this operation. Useful for forwarding on to
+	// backend SDK's that accept context. The context will also cancel if
+	// Terraform sends a cancellation signal.
+	//
+	// These functions return diagnostics, allowing developers to build
+	// a list of warnings and errors to be presented to the Terraform user.
+	// The AttributePath of those diagnostics should be built within these
+	// functions, please consult go-cty documentation for building a cty.Path
 	CreateContext CreateContextFunc
 	ReadContext   ReadContextFunc
 	UpdateContext UpdateContextFunc

helper/schema/resource_importer.go

@@ -24,7 +24,8 @@ type ResourceImporter struct {
 
 	// StateContext is called to convert an ID to one or more InstanceState to
 	// insert into the Terraform state. If this isn't specified, then
-	// the ID is passed straight through.
+	// the ID is passed straight through. This function receives a context
+	// that will cancel if Terraform sends a cancellation signal.
 	StateContext StateContextFunc
 }
 

helper/schema/schema.go

@@ -234,6 +234,20 @@ type Schema struct {
 	//
 	// ValidateDiagFunc is honored only when the schema's Type is set to TypeInt,
 	// TypeFloat, TypeString, TypeBool, or TypeMap. It is ignored for all other types.
+	//
+	// ValidateDiagFunc is also yielded the cty.Path the SDK has built up to this
+	// attribute. The SDK will automatically set the AttributePath of any returned
+	// Diagnostics to this path. Therefore the developer does not need to set
+	// the AttributePath for primitive types.
+	//
+	// In the case of TypeMap to provide the most precise information, please
+	// set an AttributePath with the additional cty.IndexStep:
+	//
+	//  AttributePath: cty.IndexStringPath("key_name")
+	//
+	// Or alternatively use the passed in path to create the absolute path:
+	//
+	//  AttributePath: append(path, cty.IndexStep{Key: cty.StringVal("key_name")})
 	ValidateDiagFunc SchemaValidateDiagFunc
 
 	// Sensitive ensures that the attribute's value does not get displayed in