Adding docs for default values (#668)

website/data/plugin-framework-nav-data.json

@@ -75,6 +75,10 @@
         "title": "Modify Plan",
         "path": "resources/plan-modification"
       },
+      {
+        "title": "Default",
+        "path": "resources/default"
+      },
       {
         "title": "Import State",
         "path": "resources/import"

website/docs/plugin/framework/migrating/attributes-blocks/default-values.mdx

@@ -7,13 +7,13 @@ description: >-
 
 # Default Values
 
-Default values set a value for an attribute when the Terraform configuration does not provide one. In SDKv2, default
-values are set via fields on an attribute's schema. In the Framework, you set default values via plan modification.
+Default values set a value for an attribute when the Terraform configuration does not provide one. In SDKv2 and the
+Framework default values are set via the `Default` field on an attribute's schema.
 Refer to
-[Plan Modification - Attribute Plan Modification](/terraform/plugin/framework/resources/plan-modification#attribute-plan-modification)
+[Default](/terraform/plugin/framework/resources/default)
 in the Framework documentation for details.
 
-This page explains how to migrate attribute defaults in SDKv2 to `AttributePlanModifier` in the Framework.
+This page explains how to migrate attribute defaults in SDKv2 to the Framework.
 
 ## SDKv2
 
@@ -37,25 +37,24 @@ func resourceExample() *schema.Resource {
 
 ## Framework
 
-In the Framework, you set default values with the `PlanModifiers` field on your attribute's definition.
+In the Framework, you set default values with the `Default` field on your attribute's definition.
 
 ```go
 func (r *resourceExample) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
     resp.Schema = schema.Schema{
         /* ... */
         Attributes: map[string]schema.Attribute{
             "attribute_example": schema.BoolAttribute{
-                PlanModifiers: []planmodifier.Bool{
-                    defaultValue(types.BoolValue(true)),
-                    /* ... */
+                Default: booldefault.StaticValue(true),
+                /* ... */
 ```
 
 ## Migration Notes
 
 Remember the following differences between SDKv2 and the Framework when completing the migration.
 
 - In SDKv2, default values are set with the `Default` or `DefaultFunc` fields on an attribute's `schema.Schema` struct.
-In the Framework, you must implement an attribute plan modifier to set default values.
+In the Framework, you must assign set the `Default` field on an attribute to set a default value.
 
 ## Example
 
@@ -86,52 +85,11 @@ func (r *exampleResource) Schema(ctx context.Context, req resource.SchemaRequest
     resp.Schema = schema.Schema{
         Attributes: map[string]schema.Attribute{
             "example_attribute": schema.Int64Attribute{
-                PlanModifiers: []planmodifier.Int64{
-                    attribute_plan_modifier.Int64DefaultValue(types.Int64Value(2048)),
-                    /* ... */
-                },
+                Default: int64default.StaticValue(2048)
                 /* ... */
             },
             /* ... */
         },
     }, nil
 }
 ```
-
-The following example implements the `Int64DefaultValue` attribute plan modifier
-that the `example_attribute` attribute uses.
-
-```go
-func Int64DefaultValue(v types.Int64) planmodifier.Int64 {
-    return &int64DefaultValuePlanModifier{v}
-}
-
-type int64DefaultValuePlanModifier struct {
-    DefaultValue types.Int64
-}
-
-var _ planmodifier.Int64 = (*int64DefaultValuePlanModifier)(nil)
-
-func (apm *int64DefaultValuePlanModifier) Description(ctx context.Context) string {
-    /* ... */
-}
-
-func (apm *int64DefaultValuePlanModifier) MarkdownDescription(ctx context.Context) string {
-    /* ... */
-}
-
-func (apm *int64DefaultValuePlanModifier) PlanModifyInt64(ctx context.Context, req planmodifier.Int64Request, res *planmodifier.Int64Response) {
-    // If the attribute configuration is not null, we are done here
-    if !req.ConfigValue.IsNull() {
-        return
-    }
-
-    // If the attribute plan is "known" and "not null", then a previous plan modifier in the sequence
-    // has already been applied, and we don't want to interfere.
-    if !req.PlanValue.IsUnknown() && !req.PlanValue.IsNull() {
-        return
-    }
-
-    res.PlanValue = apm.DefaultValue
-}
-```

website/docs/plugin/framework/resources/default.mdx

@@ -0,0 +1,43 @@
+---
+page_title: 'Plugin Development - Framework: Default'
+description: >-
+  How to set default values using the provider development framework.
+---
+
+# Default
+
+After [validation](/terraform/plugin/framework/validation) and before applying configuration changes, Terraform generates a plan that describes the expected values and behaviors of those changes. Resources can then tailor the plan to set default values on computed resource attributes that are null in the configuration.
+
+A Default can _only_ be added to a resource schema attribute.
+
+## When is a Default set?
+
+A Default is set during the [planning process](/terraform/plugin/framework/resources/plan-modification#plan-modification-process), immediately prior to the framework marking computed attributes that are null in the configuration as unknown in the plan.
+
+## Attribute Default
+
+You can supply the attribute type `Default` field with a default for that attribute. For example:
+
+```go
+// Typically within the schema.Schema returned by Schema() for a resource.
+schema.StringAttribute{
+    // ... other Attribute configuration ...
+
+    Default: stringdefault.StaticValue("str"),
+}
+
+schema.SetAttribute{
+    // ... other Attribute configuration ...
+
+    Default: setdefault.StaticValue(
+        types.SetValueMust(
+            types.StringType,
+            []attr.Value{
+                types.StringValue("str"),
+            },
+        ),
+    ),
+},
+```
+
+If defined, a default is applied to the current attribute providing that the attribute is null in the configuration. If any nested attributes define a default, then those are applied afterwards. Any default that returns an error will prevent Terraform from applying further defaults of that attribute as well as any nested attribute defaults.