Document Naga's promises around validation and panics.

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 {