hashicorp / hashicorp/terraform-plugin-docs

"Block List" confusing to user reading docs, perhaps "repeatable Block"?

Open
#47 3 comments 29 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.