Make value handling methods more discoverable in the documentation

[asaba-hashi]

Module version

N/A

Use-cases

As a new framework developer, I would like to easily find the methods for converting go native types to their equivalent type values.

The current documenation for attributes is very long and the full contents are not listed completely on the "On this page".

Attempted Solutions

N/A

Proposal

1. Add a general "types Conventions" section at the top of the page describing that each type has a "types..IsNull"/"types.ValueFrom"/etc.
2. Add links to the table at the top of the page to the content further down.
3. Expand the TOC (or do some other rearrangement of the content) such that each type has an entry in a TOC.

References

[bflad]

Just to copy some additional thoughts from an outside-of-GitHub conversation:

Another potential idea here to avoid the long scrolling single page would be to break down each data/attribute type into its own page, then each of those could spend some real estate on adding some more real world examples around going to/from the framework types

The navigation then might become something like:

Handling Data

• Terraform Concepts (existing)
• Schemas (existing)
• Attributes (converted to an overview page)
  • Bool (referencing Built-in Types > Bool)
  • Float64 (referencing Built-in Types > Float64)
  • Int64 (referencing Built-in Types > Int64)
  • List (referencing Built-in Types > List)
  • List Nested (referencing Built-in Types > List)
  • Map (referencing Built-in Types > Map)
  • Map Nested (referencing Built-in Types > Map)
  • Number (referencing Built-in Types > Number)
  • Object (referencing Built-in Types > Object)
  • Set (referencing Built-in Types > Set)
  • Set Nested (referencing Built-in Types > Set)
  • Single Nested (referencing Built-in Types > Object)
  • String (referencing Built-in Types > String)
• Blocks (converted to an overview page)
  • List (referencing Built-in Types > List)
  • Set (referencing Built-in Types > Set)
  • Single (referencing Built-in Types > Object)
• Built-in Types (new)
  • Bool (referencing Attributes > Bool)
  • Float64 (referencing Attributes > Float64)
  • Int64 (referencing Attributes > Int64)
  • List (referencing Attributes > List, Attributes > List Nested, Blocks > List)
  • Map (referencing Attributes > Map, Attributes > Map Nested)
  • Number (referencing Attributes > Number)
  • Object (referencing Attributes > Object, Blocks > Single)
  • Set (referencing Attributes > Set, Attributes > Set Nested, and Blocks > Set)
  • String (referencing Attributes > String)
• Paths (existing)
• Path Expressions (existing)
• Accessing Terraform Data (existing, although maybe could use some tweaks)
• Writing Data (existing, although maybe could use some tweaks)
• Conversion Rules (removing, these should be documented with each Built-In Type page)
• Custom Types (existing)

Each of the new Attributes, Blocks, and Built-In Types pages could then provide real world code examples, such as using MapValueFrom() to convert a map[string]string to a types.Map:

// Logic in this example is applicable to any data source, provider, or resource method
// that needs to convert data into a types.Map.
func (r ThingResource) Read(ctx context.Context, req resource.ReadRequest, resp *resource.ReadResponse) {
  // ... API handling logic ...

  // Typically this would be an existing field from an API SDK type,
  // however this example shows an inline variable definition for brevity.
  var apiMap map[string]string

  tfMap, diags := types.MapValueFrom(ctx, types.String, apiMap)

  resp.Diagnostics.Append(diags...)

  if resp.Diagnostics.HasError() {
    return
  }

  // ... resp.State.Set() or resp.State.SetAttribute() logic using tfMap ...
}

[mschuchard]

I would also really appreciate this as I struggled for about thirty minutes yesterday to determine proper usage for AsElements and MapValueFrom. I eventually dug around the relevant unit tests to figure it out. When I finally executed an acceptance test and it succeeded first try I almost fell out of my chair, and had to stare at my code for a while out of suspicion.

That example at the end of the comment would be very helpful (especially because I thought at first I needed to use basetypes.StringType{}), but also documentation for e.g. ElementsAs would be helpful in my opinion.

[bflad]

Coalescing some relevant HashiCorp Discuss references:

https://discuss.hashicorp.com/t/terraform-plugin-framework-value-conversion-error-unhandled-unknown-value/44382
https://discuss.hashicorp.com/t/how-to-set-types-set-from-read-method/48146
https://discuss.hashicorp.com/t/plugin-framework-double-nested/52689
https://discuss.hashicorp.com/t/i-need-help-with-map-object-types/53775
https://discuss.hashicorp.com/t/inappropriate-value-for-attribute-element-object-required/54850
https://discuss.hashicorp.com/t/two-dimensional-typelist-typeset/55330
https://discuss.hashicorp.com/t/handling-types-object-field-in-a-framework-model-struct/56259
https://discuss.hashicorp.com/t/issue-while-saving-listnestedattribute-in-state-file/56352
https://discuss.hashicorp.com/t/related-datatype-for-singlenestedattribute-from-types-package/56825
https://discuss.hashicorp.com/t/resource-createrequest-plan-get-throws-error-on-slice-of-struct-in-resource-model/56887

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.