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

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

Open mavogel opened this issue 3 years ago • 1 comments

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.