Add information about update-ability, default value, & validation

[drewmullen]

Terraform CLI and terraform-plugin-docs Versions

latest

Use Cases or Problem Statement

It would be nice for users to know more about a parameters behaviors without having to write lengthy custom descriptions. It would also be nice to be able to have a unified look to documentation so common questions are answered uniformly and generated instead of hand typed.

Specifically it would be nice to know a parameters:

• default value - if applicable
• updateability - if it can be updated or requires replacement
• validators - what types of validations are run against the input

Proposal

Technical implementation is currently limited by missing fields in the schema. That aside, here are some proposals for how to display the information:

- `my_parameter`: <description>
  - Type: <type>  
  - Default: "one"
  - Plan Modifiers: 
    - Forces Recreation
  - Validators:
    - Any one of: `one`, `two`, `three`

How much impact is this issue causing?

Low

Additional Information

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[austinvalle]

Hey there @drewmullen, thanks for the feature request!

As you mentioned, all the information we use today is provided by Terraform core, via the terraform providers schema -json command. Unfortunately that limits us to the information we can provide in tooling like terraform-plugin-docs or the Terraform language server.

A way forward is to start producing additional metadata from the provider binary itself (and perhaps additionally pre-generating that metadata in a static file, hosted by a CDN, etc.) so that tooling like terraform-plugin-docs can make use of it. If you (or others) are interested, we have a Framework GH issue for this exact concept: hashicorp/terraform-plugin-framework#1022

Once metadata is available from the providers, we can start giving more specific implementation metadata to downstream tools, which luckily for terraform-plugin-framework, is already defined, so the framework provider ecosystem wouldn't need to implement new interfaces to enable this.

For example: https://github.com/hashicorp/terraform-provider-aws/blob/8d8407e7ae0356cace0234d6accaf30f14a0cedf/internal/framework/validators/ip.go#L18-L21