tfsdk: Clarify Attribute and Block type DeprecationMessage field usage (

#429)

Reference: #428

tfsdk/attribute.go

@@ -73,9 +73,36 @@ type Attribute struct {
 	// file is sensitive.
 	Sensitive bool
 
-	// DeprecationMessage defines a message to display to practitioners
-	// using this attribute, warning them that it is deprecated and
-	// instructing them on what upgrade steps to take.
+	// 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.
+	//
+	// 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.
+	//
+	// 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:
+	//
+	//     https://github.com/hashicorp/terraform/issues/7569
+	//
+	// Set this field to a practitioner actionable message such as:
+	//
+	//     - "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."
+	//
 	DeprecationMessage string
 
 	// Validators define value validation functionality for the attribute. All

tfsdk/block.go

@@ -26,9 +26,24 @@ type Block struct {
 	// behaves exactly like the map of blocks on the Schema type.
 	Blocks map[string]Block
 
-	// DeprecationMessage defines a message to display to practitioners
-	// using this block, warning them that it is deprecated and
-	// instructing them on what upgrade steps to take.
+	// DeprecationMessage defines warning diagnostic details to display to
+	// practitioners configuring this Block. The warning diagnostic summary
+	// is automatically set to "Block 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 and if the practitioner
+	// configuration attempts to set the block value to a known or unknown
+	// value (which may eventually be null).
+	//
+	// Set this field to a practitioner actionable message such as:
+	//
+	//     - "Configure other_attribute instead. This block will be removed
+	//       in the next major version of the provider."
+	//     - "Remove this block's configuration as it no longer is used and
+	//       the block will be removed in the next major version of the
+	//       provider."
+	//
 	DeprecationMessage string
 
 	// Description is used in various tooling, like the language server, to

website/docs/plugin/framework/schemas.mdx

@@ -252,8 +252,19 @@ description](#markdowndescription), so too can individual attributes.
 
 ### DeprecationMessage
 
-Much like [resources, data sources, and providers can be
-deprecated](#deprecationmessage), so too can individual attributes.
+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:
+
+```text
+Warning: Attribute Deprecated
+
+{Configuration file/line information}
+
+{DeprecationMessage field value}
+```
+
+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.
 
 ### Validators