When a function is implemented, ensure the function is discoverable by practitioners with usage information.
There are two main components for function 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.
DefinitionThe function.Definition type implements the following fields:
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",
}
}
Each parameter type, whether in the definition Parameters or VariadicParameter field, implements the following fields:
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.
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 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",
},
},
}
}
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:
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.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4