More `bail!` usage

1 files changed, 9 insertions, 0 deletions

diff --git a/src/diag.rs b/src/diag.rs
index d9f88024..4fb9ecc0 100644
--- a/src/diag.rs
+++ b/src/diag.rs
@@ -13,6 +13,15 @@ use crate::syntax::{ErrorPos, Span, Spanned};
 use crate::World;
 
 /// Early-return with a [`StrResult`] or [`SourceResult`].
+///
+/// If called with just a string and format args, returns with a
+/// `StrResult`. If called with a span, a string and format args, returns
+/// a `SourceResult`.
+///
+/// ```
+/// bail!("bailing with a {}", "string result");
+/// bail!(span, "bailing with a {}", "source result");
+/// ```
 #[macro_export]
 #[doc(hidden)]
 macro_rules! __bail {