add note about stripping secrets

pkg/tfbridge/detailed_diff.go

@@ -483,6 +483,12 @@ func MakeDetailedDiffV2(
 	ps map[string]*SchemaInfo,
 	priorProps, props, newInputs resource.PropertyMap,
 ) map[string]*pulumirpc.PropertyDiff {
+	// Strip secrets and outputs from the properties before calculating the diff.
+	// This allows the rest of the algorithm to focus on the actual changes and not
+	// have to deal with the extra noise.
+	// This is safe to do here because the detailed diff we return to the engine
+	// is only represented by paths to the values and not the values themselves.
+	// The engine will then takes care of masking secrets.
 	stripSecretsAndOutputs := func(props resource.PropertyMap) resource.PropertyMap {
 		propsVal := propertyvalue.RemoveSecretsAndOutputs(resource.NewProperty(props))
 		return propsVal.ObjectValue()