[Impeller] Clarify validation log behavior. (flutter#40921)

[Impeller] Clarify validation log behavior.

impeller/base/validation.h

@@ -38,4 +38,17 @@ struct ScopedValidationDisable {
 
 }  // namespace impeller
 
+//------------------------------------------------------------------------------
+/// Get a stream to the log Impeller uses for all validation errors. The
+/// behavior of these logs is as follows:
+///
+/// * Validation error are completely ignored in the Flutter release
+///   runtime-mode.
+/// * In non-release runtime-modes, validation logs are redirected to the
+///   Flutter `INFO` log. These logs typically show up when verbose logging is
+///   enabled.
+/// * If `ImpellerValidationErrorsSetFatal` is set to `true`, validation logs
+///   are fatal. The runtime-mode restriction still applies. This usually
+///   happens in test environments.
+///
 #define VALIDATION_LOG ::impeller::ValidationLog{}.GetStream()