hashicorp / hashicorp/terraform-plugin-docs

Descriptions for nested schemas are missing (inconsistent behaviour)

Open
#28 13 comments 11 reactions 0 assignees View on GitHub
bug upstream/schema
Dominant language
Go
Stars
263
Forks
84
Avg merge
3d 6h
Merged PRs (30d)
2

Description

There are two issues:

1. A `Description` field set on the parent Schema isn't displayed any where.
2. In _some_ cases a nested Schema type(s) will not have its `Description` value pulled into the documentation.

Here's an example schema that shows a `Description` field has been set on the top-level Schema:

```go
s.Schema[h.GetKey()] = &schema.Schema{
Type: schema.TypeSet,
Required: true,
Description: "A set of Domain names to serve as entry points for your Service",
Elem: &schema.Resource{
Schema: map[string]*schema.Schema{
"name": {
Type: schema.TypeString,
Required: true,
Description: "The domain that this Service will respond to",
},
"comment": {
Type: schema.TypeString,
Optional: true,
Description: "An optional comment about the Domain.",
},
},
},
}
```

Yet when generating the documentation for this resource I discovered that description value is not present anywhere:

Screenshot 2021-01-27 at 13 40 39
Screenshot 2021-01-27 at 13 40 46

Here's an example schema definition with a nested schema under the 'rules' field:

```go
Schema: map[string]*schema.Schema{
"publishers": {
Type: schema.TypeList,
Optional: true,
Description: "A list of publishers to be used as filters for the data set.",
Elem: &schema.Schema{Type: schema.TypeString},
},
"tags": {
Type: schema.TypeList,
Optional: true,
Description: "A list of tags to be used as filters for the data set.",
Elem: &schema.Schema{Type: schema.TypeString},
},
"exclude_modsec_rule_ids": {
Type: schema.TypeList,
Optional: true,
Description: "A list of modsecurity rules IDs to be excluded from the data set.",
Elem: &schema.Schema{Type: schema.TypeInt},
},
"rules": {
Type: schema.TypeList,
Computed: true,
Description: "The list of rules that results from any given combination of filters.",
Elem: &schema.Resource{
Schema: map[string]*schema.Schema{
"modsec_rule_id": {
Type: schema.TypeInt,
Required: true,
Description: "The modsecurity rule ID.",
},
"latest_revision_number": {
Type: schema.TypeInt,
Required: true,
Description: "The modsecurity rule's latest revision.",
},
"type": {
Type: schema.TypeString,
Computed: true,
Description: "The modsecurity rule's type.",
},
},
},
},
},
```

In the generated schema output (see below example, from running `tfplugindocs generate`) we can see the `Description` fields from the top-level `Schema` types are included in the output, but the nested Schema Description fields are not included (see ``)...

```

## Schema

### Optional

- **exclude_modsec_rule_ids** (List of Number) A list of modsecurity rules IDs to be excluded from the data set.
- **id** (String) The ID of this resource.
- **publishers** (List of String) A list of publishers to be used as filters for the data set.
- **tags** (List of String) A list of tags to be used as filters for the data set.

### Read-only

- **rules** (List of Object) The list of rules that results from any given combination of filters. (see [below for nested schema](#nestedatt--rules))


### Nested Schema for `rules`

Read-only:

- **latest_revision_number** (Number)
- **modsec_rule_id** (Number)
- **type** (String)
```

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.