From ba58ef5176c576527a26719d02bd8ce4b42d1bd2 Mon Sep 17 00:00:00 2001
From: Jim Blandy <jimb@red-bean.com>
Date: Thu, 14 Apr 2022 10:15:29 -0700
Subject: [PATCH] Document Naga's promises around validation and panics.

---
 src/valid/mod.rs | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/src/valid/mod.rs b/src/valid/mod.rs
index bc1a8dc6e8..89314294fd 100644
--- a/src/valid/mod.rs
+++ b/src/valid/mod.rs
@@ -33,6 +33,21 @@ pub use r#type::{Disalignment, TypeError, TypeFlags};
 
 bitflags::bitflags! {
     /// Validation flags.
+    ///
+    /// If you are working with trusted shaders, then you may be able
+    /// to save some time by skipping validation.
+    ///
+    /// If you do not perform full validation, invalid shaders may
+    /// cause Naga to panic. If you do perform full validation and
+    /// [`Validator::validate`] returns `Ok`, then Naga promises that
+    /// code generation will either succeed or return an error; it
+    /// should never panic.
+    ///
+    /// The default value for `ValidationFlags` is
+    /// `ValidationFlags::all()`. If Naga's `"validate"` feature is
+    /// enabled, this requests full validation; otherwise, this
+    /// requests no validation. (The `"validate"` feature is disabled
+    /// by default.)
     #[cfg_attr(feature = "serialize", derive(serde::Serialize))]
     #[cfg_attr(feature = "deserialize", derive(serde::Deserialize))]
     pub struct ValidationFlags: u8 {