Improve documentation of object type for provider-defined functions

[austinvalle]

Terraform CLI and terraform-plugin-docs Versions

github.com/hashicorp/terraform-plugin-docs v0.18.0

Use Cases or Problem Statement

Currently, when documenting a provider-defined function that has an object as a parameter or return type, there is no mechanism that documents the attributes of said object.

Provider Schema

{
  "functions": {
    "rfc3339_parse": {
      "description": "Given an RFC3339 timestamp string, will parse and return an object representation of that date and time.",
      "summary": "Parse an RFC3339 timestamp string",
      "return_type": [
        "object",
        {
          "day": "number",
          "hour": "number",
          "iso_week": "number",
          "iso_year": "number",
          "minute": "number",
          "month": "number",
          "month_name": "string",
          "second": "number",
          "unix": "number",
          "weekday": "number",
          "weekday_name": "string",
          "year": "number",
          "year_day": "number"
        }
      ],
      "parameters": [
        {
          "name": "timestamp",
          "description": "RFC3339 timestamp string to parse",
          "type": "string"
        }
      ]
    }
  }
}

Documentation Output

The output currently just prints object with no indication of what attributes are available.

---
# generated by https://github.com/hashicorp/terraform-plugin-docs
page_title: "rfc3339_parse function - terraform-provider-time"
subcategory: ""
description: |-
  Parse an RFC3339 timestamp string
---

# function: rfc3339_parse

Given an RFC3339 timestamp string, will parse and return an object representation of that date and time.



## Signature

<!-- signature generated by tfplugindocs -->
```text
rfc3339_parse(timestamp string) object
```

## Arguments

<!-- arguments generated by tfplugindocs -->
1. `timestamp` (String) RFC3339 timestamp string to parse

Workaround

Currently, you'll need to document the object manually with a template, but that's only really an "escape hatch" solution and not ideal for the broader ecosystem. Example template for rfc3339_parse:

page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}"
subcategory: ""
description: |-
{{ .Summary | plainmarkdown | trimspace | prefixlines "  " }}
---

# {{.Type}}: {{.Name}}

{{ .Description | trimspace }}

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

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

## Signature

{{ .FunctionSignatureMarkdown }}

## Arguments

{{ .FunctionArgumentsMarkdown }}
{{ if .HasVariadic -}}
{{ .FunctionVariadicArgumentMarkdown }}
{{- end }}

## Return Type

The `object` returned from `rfc3339_parse` has the following attributes:
- `year` (Number) The year for the timestamp.
- `year_day` (Number) The day of the year for the timestamp, in the range [1, 365] for non-leap years, and [1, 366] in leap years.
- `day` (Number) The day of the month for the timestamp.
- `month` (Number) The month of the year for the timestamp.
- `month_name` (String) The name of the month for the timestamp (ex. "January").
- `weekday` (Number) The day of the week for the timestamp.
- `weekday_name` (String) The name of the day for the timestamp (ex. "Sunday").
- `hour` (Number) The hour within the day for the timestamp, in the range [0, 23].
- `minute` (Number) The minute offset within the hour for the timestamp, in the range [0, 59].
- `second` (Number) The second offset within the minute for the timestamp, in the range [0, 59].
- `unix` (Number) The number of seconds elapsed since January 1, 1970 UTC.
- `iso_year` (Number) The ISO 8601 year number.
- `iso_week` (Number) The ISO 8601 week number.

Proposal

Once available downstream introduce logic to generate a section for object type attributes, similar to nested attributes in resources/data source documentation.

Downstream Dependency

Currently, terraform-plugin-docs relies on the terraform providers schema -json command, which relies on the GetProviderSchema RPC. These RPCs typically only contain information that is relevant to Terraform operations and sometimes don't contain enough information for downstream tools like this doc generator or the Terraform language server. In this case, the RPC does not contain a description field for each attribute in an object.

Similar issues that are blocked by this dependency on the GetProviderSchema RPC:

• Allow setting subcategory from code #156
• bug: TypeSet/TypeList Elements are not rendered in data-sources #64

How much impact is this issue causing?

Low

Additional Information

No response

Code of Conduct

• I agree to follow this project's Code of Conduct