bug: TypeSet/TypeList Elements are not rendered in data-sources

[mavogel]

Current behavior

The descriptions of the nested elements are only rendered in the markdown of the resources, but not the datasources.

• The schema:

"ipam_config": {
	Type:        schema.TypeSet,
	Description: "The IPAM configuration options",
	Computed:    true,
	Elem: &schema.Resource{
		Schema: map[string]*schema.Schema{
			"subnet": {
				Type:        schema.TypeString,
				Description: "The subnet in CIDR form",
				Optional:    true,
				ForceNew:    true,
			},

			"ip_range": {
				Type:        schema.TypeString,
				Description: "The ip range in CIDR form",
				Optional:    true,
				ForceNew:    true,
			},

			"gateway": {
				Type:        schema.TypeString,
				Description: "The IP address of the gateway",
				Optional:    true,
				ForceNew:    true,
			},

			"aux_address": {
				Type:        schema.TypeMap,
				Description: "Auxiliary IPv4 or IPv6 addresses used by Network driver",
				Optional:    true,
				ForceNew:    true,
			},
		},
	},
},

See the rendered markdowns:

• https://github.com/kreuzwerker/terraform-provider-docker/blob/feat/doc-generation/docs/resources/network.md#nested-schema-for-ipam_config
• https://github.com/kreuzwerker/terraform-provider-docker/blob/feat/doc-generation/docs/data-sources/network.md#nested-schema-for-ipam_config

Expected behavior

The descriptions of the nested elements in datasources are also rendered in the markdown.

Versions

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

[aidan-mundy]

EDIT: This problem might only affect providers using the Terraform Plugin SDKv2. I haven't checked with a provider using the Terraform Plugin Framework

Unfortunately this also appears to affect resources.

This issue is a downstream result of the terraform providers schema -json command utilizing an output format for list/set attributes that contains limited information about the list/set contents. Further upstream, that command relies on this json marshaller, and that json is consumed in terraform-plugin-docs via the terraform-json unmarshalling library.

Example in the current format (note, many of the "string" attributes have associated Descriptions, and they are missing here due to the strange format):

"attributes": {
    "builds": {
        "type": [
            "list",
            [
                "object",
                {
                    "id": "string",
                    "images": [
                        "list",
                        [
                            "object",
                            {
                                "created_at": "string",
                                "id": "string",
                                "region": "string"
                            }
                        ]
                    ],
                    "labels": [
                        "map",
                        "string"
                    ],
                    "updated_at": "string"
                }
            ]
        ],
        "description": "Builds for this iteration.",
        "description_kind": "plain",
        "computed": true
    }
}

If I'm reading the discussion in this PR correctly, it looks like the infrastructure exists in terraform and in the downstream terraform-json to allow terraform providers schema -json to output more detailed information about nested types without moving any mountains, it just isn't being used yet.