Doc comments for autonaming (#1315)

Document AutoName based on some empirical findings

pkg/tfbridge/names.go

@@ -248,8 +248,35 @@ type AutoNameOptions struct {
 	PostTransform func(res *PulumiResource, name string) (string, error)
 }
 
-// AutoName creates custom schema for a Terraform name property which is automatically populated
-// from the resource's URN name, and transformed based on the provided options.
+// AutoName configures a property to automatically populate with auto-computed names when no values are given to it by
+// the user program.
+//
+// The auto-computed names will be based on the resource name extracted from the resource URN, and have a random suffix.
+// The lifecycle of automatic names is tied to the Pulumi resource lifecycle, so the automatic name will not change
+// during normal updates and will persist until the resource is replaced.
+//
+// If a required property is configured with AutoName, it becomes optional in the Pulumi Package Schema. Therefore
+// removing AutoName from a required property is a breaking change.
+//
+// For a quick example, consider aws.ec2.Keypair that has this code in its definition:
+//
+//	ResourceInfo{
+//	    	Fields: map[string]*SchemaInfo{
+//	    		"key_name": AutoName("keyName", 255, "-"),
+//	    	},
+//	}
+//
+// Deploying a KeyPair allocates an automatic keyName without the user having to specify it:
+//
+//	const deployer = new aws.ec2.KeyPair("deployer", {publicKey: pubKey});
+//	export const keyName = deployer.keyName;
+//
+// Running this example produces:
+//
+//	Outputs:
+//	   keyName: "deployer-6587896"
+//
+// Note how the automatic name combines the resource name from the program with a random suffix.
 func AutoName(name string, maxlength int, separator string) *SchemaInfo {
 	return &SchemaInfo{
 		Name: name,
@@ -264,8 +291,7 @@ func AutoName(name string, maxlength int, separator string) *SchemaInfo {
 	}
 }
 
-// AutoNameWithCustomOptions creates a custom schema for a Terraform name property and allows setting options to allow
-// transforms, custom separators and maxLength combinations.
+// AutoNameWithCustomOptions is similar to [AutoName] but exposes more options for configuring the generated names.
 func AutoNameWithCustomOptions(name string, options AutoNameOptions) *SchemaInfo {
 	return &SchemaInfo{
 		Name: name,

pkg/tfbridge/provider.go

@@ -1234,9 +1234,20 @@ func generateResourceName(packageName tokens.Package, moduleName string, moduleM
 	return fmt.Sprintf("%s.%s.%s", packageName, moduleName, moduleMemberName)
 }
 
-// SetAutonaming will loop all resources with a name property, and will add an auto-name property.  It will skip
-// those that already have a name mapping entry, since those may have custom overrides set in the resource
-// declaration (e.g., for length).
+// SetAutonaming auto-names all resource properties that are literally called "name".
+//
+// The effect is identical to configuring each matching property with [AutoName]. Pulumi will propose an auto-computed
+// value for these properties when no value is given by the user program. If a property was required before auto-naming,
+// it becomes optional.
+//
+// The maxLength and separator parameters configure how AutoName generates default values. See [AutoNameOptions].
+//
+// SetAutonaming will skip properties that already have a [SchemaInfo] entry in [ResourceInfo.Fields], assuming those
+// are already customized by the user. If those properties need AutoName functionality, please use AutoName directly to
+// populate their SchemaInfo entry.
+//
+// Note that when constructing a ProviderInfo incrementally, some care is required to make sure SetAutonaming is called
+// after [ProviderInfo.Resources] map is fully populated, as it relies on this map to find resources to auto-name.
 func (p *ProviderInfo) SetAutonaming(maxLength int, separator string) {
 	if p.P == nil {
 		glog.Warningln("SetAutonaming found a `ProviderInfo.P` nil. No Autonames were applied.")