Resource Import Documentation Handling

### Module version

```
v0.4.0 (not yet released)
```

### Use-cases

Provider developers will want to document whether a resource supports import and what type of import identifier(s) are supported. Tooling such as [`terraform-plugin-docs`](https://github.com/hashicorp/terraform-plugin-docs) (or similar) should be able to determine the implementation and automatically generate import documentation.

For example, most simple resources follow this simple type of documentation pattern for "passthrough" import:

- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance#import
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/rds_cluster#import
- https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/windows_virtual_machine#import
- https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/mssql_database#import

Some resources may need to document more complicated cases, such as "complex" identifiers that get split into multiple attributes:

- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy#import
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_provisioned_concurrency_config#import

The most advanced cases require documenting multiple example import identifiers (sometimes to make the process easier for practitioners, other times to workaround incomplete Read APIs):

- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_record#import
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_zone_association#import
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/security_group_rule#import
- https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloudfunctions_function#import
- https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_instance#import

### Attempted Solutions

Version 0.4.0 of the framework supports resource import via a _required_ `ImportState` method on the `Resource` type. This makes it difficult for tooling to determine if import is supported or not as it is reliant on specific implementation details, which may or may not be consistently implemented (such as the recommended `ResourceImportStateNotImplemented()` helper).

There is no current methodology for tooling to know import examples, except by describing it manually in resource descriptions.

### Proposal

Consider migrating the `ImportState` method onto its own interface type, e.g.

```go
type ResourceWithImportState interface {
Resource

ImportState(context.Context, ImportResourceStateRequest, *ImportStateResponse)
}
```

This will effectively make import support _optional_, against the design goals described in https://github.com/hashicorp/terraform-plugin-framework/blob/main/docs/design/import.md, however this means the framework can fully own the non-existent support implementation and downstream tooling will be able to easily determine if the implementation exists.

To handle documentation for all cases, an additional declarative documentation method could be added to that interface as well, e.g.

```go
type ResourceWithImportState interface {
Resource
ImportState(context.Context, ImportResourceStateRequest, *ImportStateResponse)

ImportExamples() []ImportExample
}

type ImportExample struct {
// optional
Description string

Identifier string
}
```

Potentially with helpers to make this easier for provider developers. Theoretically then, tooling could loop through those examples to fully generate import documentation for each import example such as:

``````markdown
{DESCRIPTION}

```console
$ terraform import {RESOURCE_TYPE}.example {IDENTIFIER}
```
``````

### References

- https://github.com/hashicorp/terraform-plugin-framework/issues/33