helper/schema: Clarify Schema type Deprecated field usage (#1013)

Reference: #1012

Author: bflad

helper/schema/schema.go

@@ -311,11 +311,32 @@ type Schema struct {
 	// "parent_block_name.0.child_attribute_name".
 	RequiredWith []string
 
-	// Deprecated indicates the message to include in a warning diagnostic to
-	// practitioners when this attribute is configured. Typically this is used
-	// to signal that this attribute will be removed in the future and provide
-	// next steps to the practitioner, such as using a different attribute,
-	// different resource, or if it should just be removed.
+	// Deprecated defines warning diagnostic details to display to
+	// practitioners configuring this attribute or block. The warning
+	// diagnostic summary is automatically set to "Argument is 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 value. It cannot detect practitioner
+	// configuration values that are unknown ("known after apply").
+	//
+	// 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."
+	//
 	Deprecated string
 
 	// ValidateFunc allows individual fields to define arbitrary validation

website/docs/plugin/sdkv2/schemas/schema-methods.mdx

@@ -132,11 +132,22 @@ ComputedWhen []string
 // key.
 ConflictsWith []string
 
-// When Deprecated is set, this attribute is deprecated.
+// When Deprecated is set, this attribute is deprecated and a warning
+// diagnostic will automatically be raised when it is configured.
 //
 // A deprecated field still works, but will probably stop working in near
 // future. This string is the message shown to the user with instructions on
 // how to address the deprecation.
+//
+// This warning diagnostic is only displayed during Terraform's validation
+// phase when the attribute is Required or Optional and if the practitioner
+// configuration attempts to set the attribute value to a known value. It
+// cannot detect practitioner configuration values that are unknown ("known
+// after apply").
+//
+// 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.
 Deprecated string
 
 // When Removed is set, this attribute has been removed from the schema