From 52a2e41c05499d360eb55935d81015cf78563bac Mon Sep 17 00:00:00 2001 From: Anton Tayanovskyy Date: Thu, 7 Nov 2024 16:04:53 -0500 Subject: [PATCH] Improve autonaming docstrings (#2600) A few stylistic fixes, typos, cross-linking and adding missing doc strings around the autonaming feature. --- pkg/tfbridge/info/autonaming.go | 26 +++++++++++++++++++++++--- pkg/tfbridge/info/info.go | 19 +++++++++++-------- 2 files changed, 34 insertions(+), 11 deletions(-) diff --git a/pkg/tfbridge/info/autonaming.go b/pkg/tfbridge/info/autonaming.go index db4a918b0..5aa2ab395 100644 --- a/pkg/tfbridge/info/autonaming.go +++ b/pkg/tfbridge/info/autonaming.go @@ -107,7 +107,7 @@ func AutoName(name string, maxlength int, separator string) *Schema { } } -// AutoNameOptions provides parameters to AutoName to control how names will be generated +// AutoNameOptions provides parameters to [AutoName] to control how names will be generated type AutoNameOptions struct { // A separator between name and random portions of the Separator string @@ -123,20 +123,40 @@ type AutoNameOptions struct { PostTransform func(res *PulumiResource, name string) (string, error) } +// Configures a property to automatically populate with an auto-computed name when no value is given to it by the user. +// +// The easiest way to get started with auto-computed names is by using the [AutoName] function. ComputeAutoNameDefault +// is intended for advanced use cases, to be invoked like this: +// +// &Default{ +// AutoNamed: true, +// ComputeDefault: func(ctx context.Context, opts ComputeDefaultOptions) (interface{}, error) { +// return ComputeAutoNameDefault(ctx, autoNameOptions, opts) +// }, +// } +// +// If the user did not provide any values for the configured field, ComputeAutoNameDefault will create a default value +// based on the name of the resource and a random suffix, and populate the property with this default value. For +// example, if the resource is named "deployer", the new value may look like "deployer-6587896". +// +// ComputeAutoNameDefault respects the prior state of the resource and will never attempt to replace a value that is +// already populated in the state with a fresh auto-name default. +// +// See [AutoNameOptions] for configuring how the generated default values look like. func ComputeAutoNameDefault( ctx context.Context, options AutoNameOptions, defaultOptions ComputeDefaultOptions, ) (interface{}, error) { if defaultOptions.URN == "" { - return nil, fmt.Errorf("AutoName is onnly supported for resources, expected Resource URN to be set") + return nil, fmt.Errorf("AutoName is only supported for resources, expected Resource URN to be set") } // Reuse the value from prior state if available. Note that this code currently only runs for Plugin Framework // resources, as SDKv2 based resources avoid calling ComputedDefaults in the first place in update situations. // To do that SDKv2 based resources track __defaults meta-key to distinguish between values originating from // defaulting machinery from values originating from user code. Unfortunately Plugin Framework cannot reliably - // disinguish default values, therefore it always calls ComputedDefaults. To compensate, this code block avoids + // distinguish default values, therefore it always calls ComputedDefaults. To compensate, this code block avoids // re-generating the auto-name if it is located in PriorState and reuses the old one; this avoids generating a // fresh random value and causing a replace plan. if defaultOptions.PriorState != nil && defaultOptions.PriorValue.V != nil { diff --git a/pkg/tfbridge/info/info.go b/pkg/tfbridge/info/info.go index 4740b052b..69e846e21 100644 --- a/pkg/tfbridge/info/info.go +++ b/pkg/tfbridge/info/info.go @@ -613,11 +613,14 @@ type Default struct { // Config uses a configuration variable from this package as the default value. Config string - // Deprecated. Use ComputeDefault. + // Deprecated. Use [Default.ComputeDefault]. From func(res *PulumiResource) (interface{}, error) - // ComputeDefault specifies how to compute a default value for the given property by consulting other properties - // such as the resource's URN. See [ComputeDefaultOptions] for all available information. + // ComputeDefault specifies a strategy for how to pick a default value when the user has not specified any value + // in their program. + // + // One common use case for this functionality is auto-naming, see [AutoName] for a recommended starting point + // and [ComputeAutoNameDefault] for the specific implementation. ComputeDefault func(ctx context.Context, opts ComputeDefaultOptions) (interface{}, error) // Value injects a raw literal value as the default. @@ -629,7 +632,7 @@ type Default struct { EnvVars []string } -// Configures [DefaultInfo.ComputeDefault]. +// Configures [Default.ComputeDefault]. type ComputeDefaultOptions struct { // URN identifying the Resource. Set when computing default properties for a Resource, and unset for functions. URN resource.URN @@ -1099,7 +1102,7 @@ func (m *MarshallableSchema) Unmarshal() *Schema { } } -// MarshallableDefault is the JSON-marshallable form of a Pulumi DefaultInfo value. +// MarshallableDefault is the JSON-marshallable form of a Pulumi [Default] value. type MarshallableDefault struct { AutoNamed bool `json:"autonamed,omitempty"` IsFunc bool `json:"isFunc,omitempty"` @@ -1107,7 +1110,7 @@ type MarshallableDefault struct { EnvVars []string `json:"envvars,omitempty"` } -// MarshalDefault converts a Pulumi DefaultInfo value into a MarshallableDefaultInfo value. +// MarshalDefault converts a Pulumi DefaultInfo value into a [MarshallableDefault] value. func MarshalDefault(d *Default) *MarshallableDefault { if d == nil { return nil @@ -1121,7 +1124,7 @@ func MarshalDefault(d *Default) *MarshallableDefault { } } -// Unmarshal creates a mostly-initialized Pulumi DefaultInfo value from the given MarshallableDefaultInfo. +// Unmarshal creates a mostly-initialized Pulumi [Default] value from the given [MarshallableDefault]. func (m *MarshallableDefault) Unmarshal() *Default { if m == nil { return nil @@ -1135,7 +1138,7 @@ func (m *MarshallableDefault) Unmarshal() *Default { if m.IsFunc { defInfo.ComputeDefault = func(context.Context, ComputeDefaultOptions) (interface{}, error) { - panic("transforms cannot be run on unmarshaled DefaultInfo values") + panic("transforms cannot be run on unmarshaled Default values") } } return defInfo