Support Provider-Defined Function Documentation

[bflad]

Background

Terraform 1.8 will be introducing provider-defined function support and the public Terraform Registry will support the ingress and display of provider-defined function documentation. Both parts of this feature are under active development, so this issue description may change slightly to match implementation details.

For extracting machine-readable function information from providers, the existing terraform providers schema -json command output will be updated to include the following:

{
  "format_version": "VERSION",
  "provider_schemas": {
    "PROVIDER_ADDRESS": {
      // ... existing properties ...
      "functions": {
        "format_version": "...",
        "function_signatures": {
          "FUNCTION_NAME": {
            "summary": "...", // short description
            "description": "...", // long description
            "deprecation_message": "...",
            "parameters": [
              {
                "description": "...",
                "name": "...", // display name, e.g. for function signature form
                "type": "..."
              }
            ],
            "result_type": "...",
            "variadic_parameter": {
              "description": "...",
              "name": "...", // display name, e.g. for function signature form
              "type": "..."
            }
          }
        }
      }
    }
  }
}

For ingress and display of this documentation, the public Terraform Registry expects Markdown source files in conventional file locations similar to existing managed resource and data source files. From the base directory of a provider codebase: docs/functions/NAME.md.

Proposal

Update the migrate command to automatically handle migrating website/docs/functions/NAME.* files.

Update the generate command to automatically generate provider-defined function documentation, similar to managed resource and data source documentation. Function documentation should support custom templates and those templates should support existing template functions.

The proposed conventional function documentation content is as follows:

---
page_title: contains_ip Function - terraform-provider-cidr
description: |-
  Returns a boolean whether a RFC4632 CIDR contains an IP address.
---

# Function: contains_ip

Returns a boolean whether a RFC4632 CIDR contains an IP address.

## Example Usage

```terraform
# result: true
provider::cidr::contains_ip("10.0.0.0/8", "10.0.0.1")
```

## Signature

```text
contains_ip(cidr string, ip string) bool
```

## Arguments

1. `cidr` (String) RFC4632 CIDR to check whether it contains the given IP address.
2. `ip` (String) IP address to check whether its contained in the RFC4632 CIDR.

So a default template may look like the following:

---
page_title: "{{.Name}} Function - {{ .ProviderName }}"
subcategory: ""
description: |-
{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
---

# Function: {{.Name}}

{{ .Description | trimspace }}

{{ if .HasExample -}}
## Example Usage

{{ tffile .ExampleFile }}
{{- end }}

## Signature

{{ .FunctionSignatureMarkdown }}

## Arguments

{{ .FunctionArgumentsMarkdown }}

Where the new FunctionSignatureMarkdown and FunctionArgumentsMarkdown template functions handle the business of looping through the parameters, variadic parameter, and return.

[bflad]

Initial Terraform implementation: hashicorp/terraform#34450

[bflad]

Created hashicorp/terraform-json#118 for tracking terraform-json updates necessary.

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.