hashicorp / hashicorp/terraform-plugin-docs
"Block List" confusing to user reading docs, perhaps "repeatable Block"?
- Dominant language
- Go
- Stars
- 263
- Forks
- 84
- Avg merge
- 3d 6h
- Merged PRs (30d)
- 2
Description
`(Block List)` as a type rendered in documentation makes sense to the maintainer of a provider, but IMO it's confusing or even misleading to the end user.
Concrete example here:
https://github.com/OJFord/terraform-provider-wireguard/commit/58ef3d8c27cdedae643e77b499d75fecac03246e#diff-60a95e399cf5c94cb98075600ad42997cdae1a9839f293569766d66acdaa0bcfR59
`peer` in:
```hcl
data "wireguard_config_document" "peer1" {
private_key = wireguard_asymmetric_key.peer1.private_key
listen_port = 1234
dns = [
"1.1.1.1",
"1.0.0.1",
"2606:4700:4700:0:0:0:0:64",
"2606:4700:4700:0:0:0:0:6400",
]
peer {
public_key = wireguard_asymmetric_key.peer2.public_key
allowed_ips = [
"0.0.0.0/0",
]
persistent_keepalive = 25
}
peer {
public_key = wireguard_asymmetric_key.peer3.public_key
endpoint = "example.com:51820"
allowed_ips = [
"::/0",
]
}
}
```
_to a user_ isn't a 'list', it's just a block. One that can be specified multiple times, sure, and maybe that's represented as a list behind the scenes, but as someone using the resource or data source it isn't a list.
It's rendered in docs (by `tfplugindocs` v0.4.0) as:
> - **peer** (Block List) (see [below for nested schema](#nestedblock--peer))
but I think better would be:
> - **peer** (Block, repeatable) (see [below for nested schema](#nestedblock--peer))
or 'multiple allowed', or similar.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.