Improvements to Documentation (#584)

* Cleaning up docs (#583)

* Consolidating attribute documentation in the attributes page (#583)

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

@@ -152,6 +152,10 @@
       {
         "title": "Conversion Rules",
         "path": "handling-data/conversion-rules"
+      },
+      {
+        "title": "Custom Types",
+        "path": "handling-data/custom-types"
       }
     ]
   },

website/docs/plugin/framework/getting-started/code-walkthrough.mdx

@@ -353,7 +353,9 @@ Refer to [Data Sources](/plugin/framework/data-sources) for more details and con
 
 ## Terraform Configuration
 
-With the definitions we have for [provider server](#provider-server), [provider](#provider), [resource](#resource) and [data source](#data-source), we can run the provider by specifying configuration and executing `terraform apply`.
+Refer to [terraform-provider-scaffolding-framework](https://github.com/hashicorp/terraform-provider-scaffolding-framework) for details on how to wire together a [provider server](#provider-server), [provider](#provider), [resource](#resource) and [data source](#data-source).
+
+Once wired together, run the provider by specifying configuration and executing `terraform apply`.
 
 ### Resource Configuration
 

website/docs/plugin/framework/handling-data/attributes.mdx

@@ -405,56 +405,175 @@ Call one of the following to create a `types.Set`:
 * [`types.SetValueFrom(context.Context, attr.Type, any) (types.Set, diag.Diagnostics)`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/types#SetValueFrom): A known value with the given element type and values. Can convert from standard Go types, using the [conversion rules](/plugin/framework/accessing-values#conversion-rules).
 * [`types.SetValueMust(map[string]attr.Type, map[string]attr.Value) types.Set`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/types#SetValueMust): A known value with the given element type and values. Any diagnostics are converted to a runtime panic. This is recommended only for testing or exhaustively tested logic.
 
-## Create Provider-Defined Types and Values
+### Nested Attributes
 
-You may want to build your own attribute value and type implementations to allow your provider to combine validation, description, and plan customization behaviors into a reusable bundle. This helps avoid duplication or reimplementation and ensures consistency.
+-> Only supported when using protocol version 6.
 
-~> **Important:** Specifying plan customization for attribute types is not yet
-supported, limiting their utility. Support is expected in the near future.
+[Nested attributes](/plugin/framework/handling-data/attributes#nested-attributes) enable provider developers to define objects of attributes which fully support attribute behaviors and practitioners to configure these directly using [expressions](/language/expressions).
 
-### `attr.Type` Interface
+#### SingleNestedAttribute
 
-Use the [`attr.Type`
-interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/attr#Type)
-to implement an attribute type. It tells Terraform about its constraints and tells the framework how to create new attribute values from the information Terraform supplies. `attr.Type` has the following methods.
+With single nested attributes, the attribute behaves like an object. The practitioner can only specify one definition of the nested attributes.
 
-| Method               | Description                                                                                                                                                                                                                                                                                                                |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TerraformType`      | Returns the [`tftypes.Type` value](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-go/tftypes#Type) that describes its type constraints. This is how Terraform will know what type of values it can accept.                                                                                                       |
-| `ValueFromTerraform` | Returns an attribute value from the [`tftypes.Value`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-go/tftypes#Value) that Terraform supplies, or to return an error if it cannot. This error should not be used for validation purposes, and is expected to indicate programmer error, not practitioner error. |
-| `Equal`              | Returns true if the attribute type is considered equal to the passed attribute type.                                                                                                                                                                                                                                       |
+```tf
+resource "example_foo" "bar" {
+  nested_attribute = {
+    hello = "world"
+    demo = true
+  }
+}
+```
 
-### `AttributePathStepper` Interface
+```go
+func (e *exampleResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
+    resp.Schema = schema.Schema{
+        Attributes: map[string]schema.Attribute{
+            "nested_attribute": schema.SingleNestedAttribute{
+                /* ... */
+                Attributes: map[string]schema.Attribute{
+                    "hello": schema.StringAttribute{
+                        /* ... */
+                    },
+                    "demo": schema.BoolAttribute{
+                        /* ... */
+                    },
+                },
+            },
+        },
+    }
+}
+```
 
-All attribute types must implement the [`tftypes.AttributePathStepper`
-interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-go/tftypes#AttributePathStepper),
-so the framework can access element or attribute types using attribute paths.
+#### ListNestedAttribute
 
-### `xattr.TypeWithValidation` Interface
+With list nested attributes, the attribute behaves like a list of objects. The practitioner can
+specify any number of groups of these attributes.
 
-If validation for type values is desired, use the [`xattr.TypeWithValidation` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/attr/xattr#TypeWithValidation) to include validation logic for type values. The framework will call this functionality when validating all values based on the schema.
+```tf
+resource "example_foo" "bar" {
+  nested_attribute = [
+    {
+      hello = "world"
+      demo = true
+    },
+    {
+      hello = "moon"
+      demo = false
+    },
+  ]
+}
+```
 
-| Method     | Description                                                   |
-| ---------- | ------------------------------------------------------------- |
-| `Validate` | Returns any warning or error diagnostics for the given value. |
+```go
+func (e *exampleResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
+    resp.Schema = schema.Schema{
+        Attributes: map[string]schema.Attribute{
+            "nested_attribute": schema.ListNestedAttribute{
+                /* ... */
+                NestedObject: schema.NestedAttributeObject{
+                    Attributes: map[string]schema.Attribute{
+                        "hello": schema.StringAttribute{
+                            /* ... */
+                        },
+                        "demo": schema.BoolAttribute{
+                            /* ... */
+                        },
+                    },
+                },
+            },
+        },
+    }
+}
+```
 
-### Type-Specific Interfaces
+#### MapNestedAttribute
 
-| Case                        | Interface                                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Elements of the same type   | [`TypeWithElementType`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/attr#TypeWithElementType)       | Attribute types that contain elements of the same type, like maps and lists, are required to implement `attr.TypeWithElementType`, which adds `WithElementType` and `ElementType` methods to the `attr.Type` interface. `WithElementType` must return a copy of the attribute type, but with its element type set to the passed type. `ElementType` must return the attribute type's element type.                         |
-| Elements of different types | [`TypeWithElementTypes`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/attr#TypeWithElementType)      | Attribute types that contain elements of differing types, like tuples, are required to implement the `attr.TypeWithElementTypes`, which adds `WithElementTypes` and `ElementTypes` methods to the `attr.Type` interface. `WithElementTypes` must return a copy of the attribute type, but with its element types set to the passed element types. `ElementTypes` must return the attribute type's element types.           |
-| Contain attributes          | [`TypeWithAttributeTypes`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/attr#TypeWithAttributeTypes) | Attribute types that contain attributes, like objects, are required to implement the `attr.TypeWithAttributeTypes` interface, which adds `WithAttributeTypes` and `AttributeTypes` methods to the `attr.Type` interface. `WithAttributeTypes` must return a copy of the attribute type, but with its attribute types set to the passed attribute types. `AttributeTypes` must return the attribute type's attribute types. |
+With map nested attributes, the attribute behaves like a map of objects. The practitioner can
+specify any number of groups of these attributes, with string keys associated
+with each group.
 
-### `attr.Value` Interface
+```tf
+resource "example_foo" "bar" {
+  nested_attribute = {
+    "red" = {
+      hello = "world"
+      demo = true
+    },
+    "blue" = {
+      hello = "moon"
+      demo = false
+    },
+  }
+}
+```
+
+```go
+func (e *exampleResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
+    resp.Schema = schema.Schema{
+        Attributes: map[string]schema.Attribute{
+            "nested_attribute": schema.MapNestedAttribute{
+                /* ... */
+                NestedObject: schema.NestedAttributeObject{
+                    Attributes: map[string]schema.Attribute{
+                        "hello": schema.StringAttribute{
+                            /* ... */
+                        },
+                        "demo": schema.BoolAttribute{
+                            /* ... */
+                        },
+                    },
+                },
+            },
+        },
+    }
+}
+```
+
+#### SetNestedAttribute
+
+With set nested attributes, the attributes behave like a set of objects. The practitioner can
+specify any number of groups of these attributes.
+
+```tf
+resource "example_foo" "bar" {
+  nested_attribute = [
+    {
+      hello = "world"
+      demo = true
+    },
+    {
+      hello = "moon"
+      demo = false
+    },
+  ]
+}
+```
+
+```go
+func (e *exampleResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
+    resp.Schema = schema.Schema{
+        Attributes: map[string]schema.Attribute{
+            "nested_attribute": schema.SetNestedAttribute{
+                Optional: true,
+                NestedObject: schema.NestedAttributeObject{
+                    Attributes: map[string]schema.Attribute{
+                        "hello": schema.StringAttribute{
+                            /* ... */
+                        },
+                        "demo": schema.BoolAttribute{
+                            /* ... */
+                        },
+                    },
+                },
+            },
+        },
+    }
+}
+```
+
+## Create Provider-Defined Types and Values
+
+You may want to build your own attribute value and type implementations to allow your provider to combine validation, description, and plan customization behaviors into a reusable bundle. This helps avoid duplication or reimplementation and ensures consistency.
 
-Use the [`attr.Value`
-interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/attr#Value)
-to implement an attribute value. It tells the framework how to express that
-attribute value in a way that Terraform will understand. `attr.Value` has the
-following methods.
+Refer to [Custom Types](plugin/framework/handling-data/custom-types) for further details on creating provider-defined types and values.
 
-| Method             | Description                                                                                                                                                                                                                     |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ToTerraformValue` | Returns a Go type that is valid input for [`tftypes.NewValue`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-go/tftypes#NewValue) for the `tftypes.Type` specified by the `attr.Type` that creates the `attr.Value`. |
-| `Equal`            | Returns true if the passed attribute value should be considered to the attribute value the method is being called on. The passed attribute value is not guaranteed to be of the same Go type.                                   |

website/docs/plugin/framework/handling-data/blocks.mdx

@@ -8,7 +8,7 @@ description: >-
 
 The Terraform language uses a block as a container for other attributes and blocks. Terraform implements many top level blocks, such as `provider` and `resource`, while providers can implement nested blocks in their schema to enable practitioners to configure data.
 
--> Use [nested attributes](/plugin/framework/handling-data/terraform-concepts#nested-attributes) for new schema implementations. Block support is mainly for migrating prior SDK-based providers.
+-> Use [nested attributes](/plugin/framework/handling-data/attributes#nested-attributes) for new schema implementations. Block support is mainly for migrating prior SDK-based providers.
 
 In this example, the Terraform-defined `resource` block contains a provider-defined `ami` attribute and `network_interface` block.