Document Functions

When a function is implemented, ensure the function is discoverable by practitioners with usage information.

There are two main components for function documentation:

Implementation-Based Documentation: Exposes function documentation to Terraform and downstream tooling, such as practitioner configuration editor integrations.
Registry-Based Documentation: Exposes function documentation to the Terraform Registry when the provider is published, making it displayed and discoverable on the web.

Implementation-Based Documentation

Add documentation directly inside the function definition. All implementation-based documentation is passed to Terraform, which downstream tooling such as pracitioner configuration editor integrations will automatically display.

Definition

The function.Definition type implements the following fields:

Field Name	Description
`Summary`	A short description of the function and its return, preferably a single sentence.
`Description`	Longer documentation about the function, its return, and pertinent implementation details in plaintext format.
`MarkdownDescription`	Longer documentation about the function, its return, and pertinent implementation details in Markdown format.

If there are no description formatting differences, set only one of Description or MarkdownDescription. When Terraform has not sent a preference for the description formatting, the framework will return MarkdownDescription if both are defined.

In this example, the function definition sets summary and description documentation:

func (f *CidrContainsIpFunction) Definition(ctx context.Context, req function.DefinitionRequest, resp *function.DefinitionResponse) {
    resp.Definition = function.Definition{
        // ... other fields ...
        Summary:     "Check if a network CIDR contains an IP",
        Description: "Returns a boolean whether a RFC4632 CIDR contains an IP address",
    }
}

Parameters

Each parameter type, whether in the definition Parameters or VariadicParameter field, implements the following fields:

Field Name	Description
`Name`	Required: Single word or abbreviation of parameter for function signature generation. If name is not provided, a runtime error will be generated.
`Description`	Documentation about the parameter and its expected values in plaintext format.
`MarkdownDescription`	Documentation about the parameter and its expected values in Markdown format.

The name must be unique in the context of the function definition. It is used for documentation purposes and displayed in error diagnostics presented to practitioners. The name should delineate the purpose of the parameter, especially to disambiguate between multiple parameters, such as the words cidr and ip in a generated function signature like cidr_contains_ip(cidr string, ip string) bool.

In this example, the function parameters set name and description documentation:

func (f *CidrContainsIpFunction) Definition(ctx context.Context, req function.DefinitionRequest, resp *function.DefinitionResponse) {
    resp.Definition = function.Definition{
        // ... other fields ...
        Parameters: []function.Parameter{
            function.StringParameter{
                Name:        "cidr",
                Description: "RFC4632 CIDR to check whether it contains the given IP address",
            },
            function.StringParameter{
                Name:        "ip",
                Description: "IP address to check whether its contained in the RFC4632 CIDR",
            },
        },
    }
}

Registry-Based Documentation

Add Markdown documentation files in conventional provider codebase locations before publishing to the Terraform Registry. The documentation is displayed and discoverable on the web. These files can be manually created or automatically generated using tooling such as terraform-plugin-docs.

The Registry provider documentation covers the overall requirements, conventional file layout details, and how to enable additional features such as sub-categories for the navigation sidebar. Function documentation for most providers is expected under the docs/functions/ directory with a file named after the function and with the extension .md. Older providers using the legacy file layout use website/docs/functions/ and .html.md.

Functions are conventionally documented with the following:

Description
Example Usage
Signature
Arguments

In this example, a docs/functions/contains_ip.md file (either manually or automatically created) will be displayed in the Terraform Registry after provider publishing:

---
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.