[Proposal]: Populate description fields in resource schema

[breathingdust]

Description

Both terraform-plugin-sdk and terraform-plugin-framework based resources allow the configuration of descriptions at the attribute and resource level. This can defined as either plain-text or markdown. The AWS Provider has historically not filled these attributes in, instead relying on hand written documentation for each resource.

It would be beneficial for various downstream tooling to have these populated (ie):

• terraform-ls
• terraform-vscode
• Sublime Terraform
• Terraform CDK

To enable this we would ideally need to rely on tooling to generate the bulk of the registry documentation from the schema descriptions, but allow overrides and customizations to provide examples notes and callouts. Contributors should not be responsible for maintaining documentation in two places. Examine the ease of documentation contribution via hand written fields or maintaining description fields.

Potential Implementation Ideas

• Create tooling to backfill description fields from existing hand-written documentation and keep them in sync and validate whether fields were missing.
• Extend terraform-plugin-docs to be able to handle any common example formatting.
• Backfill examples and notes into override templates
• Test and compare generated vs handwritten versions, once satisfied registry should use generated versions and contributor documentation should be updated accordingly.

Affected Resource(s) and/or Data Source(s)

No response

Potential Terraform Configuration

No response

References

• https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework@v1.1.0/resource/schema#Schema
• https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk@v1.17.2/helper/schema#Schema

Would you like to implement a fix?

None

[github-actions[bot]]

Community Note

Voting for Prioritization

• Please vote on this issue by adding a 👍 reaction to the original post to help the community and maintainers prioritize this request.
• Please see our prioritization guide for information on how we prioritize.
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request.

Volunteering to Work on This Issue

• If you are interested in working on this issue, please leave a comment.
• If this would be your first contribution, please review the contribution guide.