bug: attribute descriptions are not rendered in read-only nested block

[mavogel]

Current behavior

Given the schema entry with the surrounding type is and all attributes are Computed: true,:

"network_data": {
	Type:        schema.TypeList,
	Description: "The data of the networks the container is connected to",
        Computed:    true,
	Elem: &schema.Resource{
		Schema: map[string]*schema.Schema{
			"network_name": {
				Type:        schema.TypeString,
				Description: "The name of the network",
				Computed:    true,
			},
			"ip_address": {
				Type:        schema.TypeString,
				Description: "The IP address of the container.",
				Computed:    true,
				Deprecated:  "Use `network_data` instead. The IP address of the container's first network it.",
			},
			"ip_prefix_length": {
				Type:        schema.TypeInt,
				Description: "The IP prefix length of the container.",
				Computed:    true,
				Deprecated:  "Use `network_data` instead. The IP prefix length of the container as read from its NetworkSettings.",
			},
			"gateway": {
				Type:        schema.TypeString,
				Description: "The network gateway of the container.",
				Computed:    true,
				Deprecated:  "Use `network_data` instead. The network gateway of the container as read from its NetworkSettings.",
			},
			"global_ipv6_address": {
				Type:        schema.TypeString,
				Description: "The IPV6 address of the container",
				Computed:    true,
			},
			"global_ipv6_prefix_length": {
				Type:        schema.TypeInt,
				Description: "The IPV6 prefix length address of the container",
				Computed:    true,
			},
			"ipv6_gateway": {
				Type:        schema.TypeString,
				Description: "The IPV6 gateway of the container",
				Computed:    true,
			},
		},
	},
},

the rendered output is

<a id="nestedatt--network_data"></a>
### Nested Schema for `network_data`

Read-Only:

- **gateway** (String)
- **global_ipv6_address** (String)
- **global_ipv6_prefix_length** (Number)
- **ip_address** (String)
- **ip_prefix_length** (Number)
- **ipv6_gateway** (String)
- **network_name** (String)

Desired behavior

Where I like to see this output:

<a id="nestedblock--network_data"></a>
### Nested Schema for `network_data`

Read-Only:

- **gateway** (String, Deprecated) The network gateway of the container.
- **global_ipv6_address** (String) The IPV6 address of the container
- **global_ipv6_prefix_length** (Number) The IPV6 prefix length address of the container
- **ip_address** (String, Deprecated) The IP address of the container.
- **ip_prefix_length** (Number, Deprecated) The IP prefix length of the container.
- **ipv6_gateway** (String) The IPV6 gateway of the container
- **network_name** (String) The name of the network

For the surrounding type with Optional: true, the rendering works as expected.

Versions

• terraform-plugin-docs: v0.4.0
• terraform-plugin-sdk/v2 v2.6.1

[Shocktrooper]

I also have run into this and was wondering when the fix would be implemented as having descriptions on nested blocks would be nice for end users

[stevenpaz]

I too have run into this issue. Upgraded to the latest (v0.13.0 at the time of this comment) but still seeing it.

[mavogel]

Hi folks, after some digging I guess the bug is in terraform-json which this tool uses as input. For more details see the issue here: hashicorp/terraform-json#65

[sergiught]

We're hitting the same issue, it would be nice to actually get some support from HashiCorp on this.

[mavogel]

@bookshelfdave will you take over from here on? As Radek suggested in hashicorp/terraform-json#65 it could also be an issue in the https://github.com/hashicorp/terraform-plugin-sdk repo. Also the bug still exists for

terraform-plugin-docs: v0.13.0
terraform-plugin-sdk/v2 v2.24.1

[sergiught]

Would it be possible to get any ETA on this @bookshelfdave, @austinvalle? 🙏🏻

[bookshelfdave]

Hello - my apologies for the delay on this issue. Unfortunately, it is not something we can fix as part of terraform-plugin-docs. Object attributes in Terraform do not have descriptions, so there isn't a valid source for this info. This is not a limitation in Terraform Plugin Framework-based providers when using Nested Attributes.

[sergiught]

Understood, thanks for the clarity on this one @bookshelfdave 👍🏻

[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.