doc: Adds extra documentation on the ApplyReplacement logic

Author: EspenAlbert

internal/common/customplanmodifier/unknown_replacement.go

@@ -37,7 +37,7 @@ type UnknownReplacements[ResourceInfo any] struct {
 
 // AddReplacement call will only be used if the attribute is Unknown in the plan. Only valid for `computed` attributes.
 func (u *UnknownReplacements[ResourceInfo]) AddReplacement(name string, call UnknownReplacementCall[ResourceInfo]) {
-	// todo: Validate the name exists in the schema CLOUDP-309460
+	// todo: Validate the name exists in the schema and that the attribute is marked with `computed` CLOUDP-309460
 	_, found := u.Replacements[name]
 	if found {
 		panic(fmt.Sprintf("Replacement already exists for %s", name))
@@ -65,6 +65,8 @@ func (u *UnknownReplacements[ResourceInfo]) AddKeepUnknownsExtraCall(call AddKee
 // If there is no explicit replacement function, it will use the default replacer that respects the keepUnknown attributes.
 // The calls are done top-down, for example replication_specs.*.id before replication_specs.*.region_configs.*.electable_specs
 // Same levels are sorted alphabetically, for example ...region_configs.electable_specs before ...region_configs.read_only_specs
+// If the replacement function is called for a path that is an ancestor of another path, it will skip the replacement for the child path.
+// For example: if ..read_only_specs has a replacement function and is called then ..read_only_specs.disk_iops will not be called or use keepUnknown logic.
 func (u *UnknownReplacements[ResourceInfo]) ApplyReplacements(ctx context.Context, diags *diag.Diagnostics) {
 	replacedPaths := []path.Path{}
 	ancestorHasProcessed := func(p path.Path) bool {

internal/service/advancedclustertpf/model_to_ClusterDescription20240805.go

@@ -94,6 +94,7 @@ func newReplicationSpec20240805(ctx context.Context, input types.List, diags *di
 	resp := make([]admin.ReplicationSpec20240805, len(input.Elements()))
 	for i := range elements {
 		item := &elements[i]
+		// Choosing to never send ZoneId in PATCH request. It is inferred by the backend.
 		resp[i] = admin.ReplicationSpec20240805{
 			Id:            conversion.NilForUnknownOrEmptyString(item.ExternalId),
 			RegionConfigs: newCloudRegionConfig20240805(ctx, item.RegionConfigs, diags),

internal/service/advancedclustertpf/plan_modifier.go

@@ -19,7 +19,6 @@ var (
 		"electable_specs":        analyticsAndElectableSpecsReplaceUnknown,
 		"auto_scaling":           autoScalingReplaceUnknown,
 		"analytics_auto_scaling": autoScalingReplaceUnknown,
-		// TODO: Add the other computed attributes
 	}
 	// Change mappings uses `attribute_name`, it doesn't care about the nested level.
 	// However, it doesn't stop calling `replication_specs.**.attribute_name`.