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

[OJFord]

(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:
OJFord/terraform-provider-wireguard@58ef3d8#diff-60a95e399cf5c94cb98075600ad42997cdae1a9839f293569766d66acdaa0bcfR59

peer in:

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)

but I think better would be:

• peer (Block, repeatable) (see below for nested schema)

or 'multiple allowed', or similar.

[alekc]

Also, I would argue that if it's a TypeList with MaxLength=1 (which is a fairly common pattern), it should be rendered simply as "Block" since for the end user that's what it is and it will unlikely to change down the road.

[OJFord]

That's a good point. With my suggestion of , repeatable, that could just be omitted if max 1. Or perhaps changed to specify the maximum if set, regardless of value.

[yener-azs]

I met the same here (kubernetes provider) https://registry.terraform.io/providers/hashicorp/kubernetes/2.35.1/docs/resources/cluster_role#rule-4 for
rule (Block List) . It is also mentionedList of PolicyRulesand, as OP mentions, it is confusing or even misleading to the end user.
But compared to the documentation here (AWS provider): https://registry.terraform.io/providers/hashicorp/aws/5.83.1/docs/resources/security_group#ingress-6 :
ingress - (Optional) Configuration block for ingress rules. Can be specified multiple times for each ingress rule, the type(Block List) is not mentioned and what is mentioned is that "Can be specified multiple times for each ingress rule" seems more suitable and not creating confusion as (Block List) is doing. So specified multiple times is what @OJFord suggested by "(Block, repeatable)". I guess the (different) provider maintainers need to agree on a common way in the case of repeatable blocks inside of resource, data.