tfsdk: Clarify Attribute type DeprecationMessage documentation for Terraform 1.2.7 and later (#443)

Reference: hashicorp/terraform#31576

Author: bflad

tfsdk/attribute.go

@@ -79,35 +79,39 @@ type Attribute struct {
 	// file is sensitive.
 	Sensitive bool
 
-	// DeprecationMessage defines warning diagnostic details to display to
-	// practitioners configuring this Attribute. The warning diagnostic summary
-	// is automatically set to "Attribute Deprecated" along with configuration
-	// source file and line information.
+	// DeprecationMessage defines warning diagnostic details to display when
+	// practitioner configurations use this Attribute. The warning diagnostic
+	// summary is automatically set to "Attribute Deprecated" along with
+	// configuration source file and line information.
 	//
-	// This warning diagnostic is only displayed during Terraform's validation
-	// phase when this field is a non-empty string, when the Attribute is
-	// Required or Optional, and if the practitioner configuration attempts to
-	// set the attribute value to a known or unknown value (which may
-	// eventually be null). It cannot detect practitioner configuration values
-	// set directly to null, as there is no way for the framework to
-	// differentiate between an unset and null configuration due to how
-	// Terraform sends configuration information across the protocol, however
-	// this is unlikely in a real world configuration.
+	// Set this field to a practitioner actionable message such as:
 	//
-	// This field has no effect when the Attribute is Computed-only (read-only;
-	// not Required or Optional) and a practitioner attempts to reference
-	// this Attribute value in their configuration. There is a Terraform
-	// feature request to support this type of functionality:
+	//  - "Configure other_attribute instead. This attribute will be removed
+	//    in the next major version of the provider."
+	//  - "Remove this attribute's configuration as it no longer is used and
+	//    the attribute will be removed in the next major version of the
+	//    provider."
 	//
-	//     https://github.com/hashicorp/terraform/issues/7569
+	// In Terraform 1.2.7 and later, this warning diagnostic is displayed any
+	// time a practitioner attempts to configure a value for this attribute and
+	// certain scenarios where this attribute is referenced.
 	//
-	// Set this field to a practitioner actionable message such as:
+	// In Terraform 1.2.6 and earlier, this warning diagnostic is only
+	// displayed when the Attribute is Required or Optional, and if the
+	// practitioner configuration sets the value to a known or unknown value
+	// (which may eventually be null). It has no effect when the Attribute is
+	// Computed-only (read-only; not Required or Optional).
+	//
+	// Across any Terraform version, there are no warnings raised for
+	// practitioner configuration values set directly to null, as there is no
+	// way for the framework to differentiate between an unset and null
+	// configuration due to how Terraform sends configuration information
+	// across the protocol.
+	//
+	// Additional information about deprecation enhancements for read-only
+	// attributes can be found in:
 	//
-	//     - "Configure other_attribute instead. This attribute will be removed
-	//       in the next major version of the provider."
-	//     - "Remove this attribute's configuration as it no longer is used and
-	//       the attribute will be removed in the next major version of the
-	//       provider."
+	//  - https://github.com/hashicorp/terraform/issues/7569
 	//
 	DeprecationMessage string
 

website/docs/plugin/framework/schemas.mdx

@@ -252,7 +252,7 @@ description](#markdowndescription), so too can individual attributes.
 
 ### DeprecationMessage
 
-Individual attributes can be deprecated similar to resources, data sources, and providers. When the `DeprecationMessage` value is a non-empty string, the framework will automatically raise a warning diagnostic to practitioners if a configuration value (known or unknown) is detected for the attribute during Terraform's validation phase:
+Individual attributes can be deprecated similar to resources, data sources, and providers. When the `DeprecationMessage` value is a non-empty string, the framework will automatically raise a warning diagnostic to practitioners if a configuration value (known or unknown) or reference is detected for the attribute during Terraform's validation phase:
 
 ```text
 Warning: Attribute Deprecated
@@ -264,7 +264,7 @@ Warning: Attribute Deprecated
 
 Use a practitioner actionable recommendation in `DeprecationMessage`, such as `"Configure other_attribute instead. This attribute will be removed in the next major version of the provider."` or `"Remove this attribute's configuration as it no longer is used and the attribute will be removed in the next major version of the provider."`.
 
-~> **NOTE**: This warning diagnostic is only raised for configurable (`Required` or `Optional`) attributes when a configuration value is detected. A warning diagnostic is not raised for read-only (`Computed` only) attributes when referenced.
+~> **NOTE**: In Terraform 1.2.6 and earlier, a deprecation warning diagnostic is only raised for configurable (`Required` or `Optional`) attributes when a configuration value is detected. A warning diagnostic is not raised for read-only (`Computed` only) attributes when referenced.
 
 ### Validators