From 1298fcd41259c2cf66306cce2453efd2c19f445d Mon Sep 17 00:00:00 2001 From: Brian Flad Date: Fri, 12 Jan 2024 20:49:38 +0100 Subject: [PATCH] Add missing function deprecation_message to JSON output and website documentation (#34520) Reference: https://github.com/hashicorp/terraform/pull/34450 --- internal/command/jsonfunction/function.go | 16 ++-- internal/plugin/convert/functions.go | 1 + internal/plugin6/convert/functions.go | 1 + internal/providers/functions.go | 7 +- .../docs/cli/commands/providers/schema.mdx | 76 ++++++++++++++++++- 5 files changed, 92 insertions(+), 9 deletions(-) diff --git a/internal/command/jsonfunction/function.go b/internal/command/jsonfunction/function.go index f5c851030d..e4c40d139b 100644 --- a/internal/command/jsonfunction/function.go +++ b/internal/command/jsonfunction/function.go @@ -33,6 +33,11 @@ type FunctionSignature struct { // Summary is the optional shortened description of the function Summary string `json:"summary,omitempty"` + // DeprecationMessage is an optional message that indicates that the + // function should be considered deprecated and what actions should be + // performed by the practitioner to handle the deprecation. + DeprecationMessage string `json:"deprecation_message,omitempty"` + // ReturnTypes is the ctyjson representation of the function's // return types based on supplying all parameters using // dynamic types. Functions can have dynamic return types. @@ -147,11 +152,12 @@ func marshalProviderFunction(f providers.FunctionDecl) *FunctionSignature { } return &FunctionSignature{ - Description: f.Description, - Summary: f.Summary, - ReturnType: f.ReturnType, - Parameters: p, - VariadicParameter: vp, + Description: f.Description, + Summary: f.Summary, + DeprecationMessage: f.DeprecationMessage, + ReturnType: f.ReturnType, + Parameters: p, + VariadicParameter: vp, } } diff --git a/internal/plugin/convert/functions.go b/internal/plugin/convert/functions.go index 16350ef5e1..439068696c 100644 --- a/internal/plugin/convert/functions.go +++ b/internal/plugin/convert/functions.go @@ -33,6 +33,7 @@ func FunctionDeclFromProto(protoFunc *tfplugin5.Function) (providers.FunctionDec ret.Description = protoFunc.Description ret.DescriptionKind = schemaStringKind(protoFunc.DescriptionKind) ret.Summary = protoFunc.Summary + ret.DeprecationMessage = protoFunc.DeprecationMessage if err := json.Unmarshal(protoFunc.Return.Type, &ret.ReturnType); err != nil { return ret, fmt.Errorf("invalid return type constraint: %s", err) diff --git a/internal/plugin6/convert/functions.go b/internal/plugin6/convert/functions.go index 98bf4cec43..957ed1d719 100644 --- a/internal/plugin6/convert/functions.go +++ b/internal/plugin6/convert/functions.go @@ -33,6 +33,7 @@ func FunctionDeclFromProto(protoFunc *tfplugin6.Function) (providers.FunctionDec ret.Description = protoFunc.Description ret.DescriptionKind = schemaStringKind(protoFunc.DescriptionKind) ret.Summary = protoFunc.Summary + ret.DeprecationMessage = protoFunc.DeprecationMessage if err := json.Unmarshal(protoFunc.Return.Type, &ret.ReturnType); err != nil { return ret, fmt.Errorf("invalid return type constraint: %s", err) diff --git a/internal/providers/functions.go b/internal/providers/functions.go index c24abade41..dc8595ac75 100644 --- a/internal/providers/functions.go +++ b/internal/providers/functions.go @@ -22,9 +22,10 @@ type FunctionDecl struct { VariadicParameter *FunctionParam ReturnType cty.Type - Description string - DescriptionKind configschema.StringKind - Summary string + Description string + DescriptionKind configschema.StringKind + Summary string + DeprecationMessage string } type FunctionParam struct { diff --git a/website/docs/cli/commands/providers/schema.mdx b/website/docs/cli/commands/providers/schema.mdx index 3b2490037b..6c0ef5351e 100644 --- a/website/docs/cli/commands/providers/schema.mdx +++ b/website/docs/cli/commands/providers/schema.mdx @@ -45,8 +45,10 @@ To avoid excessive repetition, we've split the complete format into several disc The JSON output format consists of the following objects and sub-objects: - [Providers Schema Representation](#providers-schema-representation) - the top-level object returned by `terraform providers schema -json` -- [Schema Representation](#schema-representation) - a sub-object of providers, resources, and data sources that describes their schema +- [Schema Representation](#schema-representation) - a sub-object of providers, resources, and data sources that describes their schema, along with function signatures - [Block Representation](#block-representation) - a sub-object of schemas that describes attributes and nested blocks +- [Function Signature Representation](#function-signature-representation) - a sub-object of functions that describes parameters, the return, and additional documentation +- [Parameter Representation](#parameter-representation) - a sub-object of function signatures that describes their type and additional documentation ## Providers Schema Representation @@ -71,6 +73,20 @@ The JSON output format consists of the following objects and sub-objects: // data source's schema "data_source_schemas": { "example_datasource_name": , + }, + + // "functions" describes the provider functions + "functions": { + // "format_version" describes the format version for the function + // signatures. + "format_version": "1.0", + + // "function_signatures" describes the signatures for all + // available functions. + "function_signatures": { + // keys in this map are the function names, such as "abs" + "example_function": + } } }, "example_provider_two": { … } @@ -149,3 +165,61 @@ A block representation contains "attributes" and "block_types" (which represent } } ``` + +## Function Signature Representation + +A function signature describes the definition of a function. + +```javascript +{ + // "summary" is a shortened English-language description of + // the purpose of the function in Markdown. + "summary": "string", + + // "description" is a longer English-language description of + // the purpose and usage of the function in Markdown. + "description": "string", + + // "deprecation_message" when present signals that the function is deprecated + // and the message contains practitioner-facing actions for the deprecation. + "deprecation_message": "string", + + // "return_type" is a representation of a type specification + // that the function returns. + "return_type": "string", + + // "parameters" is an optional list of the positional parameters + // that the function accepts. + "parameters": [ + , + // ... + ], + + // "variadic_parameter" is an optional representation of the + // additional arguments that the function accepts after those + // matching with the fixed parameters. + "variadic_parameter": +} +``` + +## Parameter Representation + +A parameter representation describes a parameter to a function. + +```javascript +{ + // "name" is the internal name of the parameter + "name": "string", + + // "description" is an optional English-language description of + // the purpose and usage of the parameter in Markdown. + "description": "string", + + // "is_nullable" is true if null is acceptable value for the argument + "is_nullable": bool, + + // "type" is a representation of a type specification + // that the parameter's value must conform to. + "type": "string" +} +```