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

@@ -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 {

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,15 +1102,15 @@ 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"`
 	Value     interface{} `json:"value,omitempty"`
 	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