Document round trip ability (#1052)

src/lib.rs

@@ -21,7 +21,7 @@
 //! 2. [`ast`] for the AST structure
 //! 3. [`Dialect`] for supported SQL dialects
 //!
-//! # Example
+//! # Example parsing SQL text
 //!
 //! ```
 //! use sqlparser::dialect::GenericDialect;
@@ -39,6 +39,24 @@
 //! println!("AST: {:?}", ast);
 //! ```
 //!
+//! # Creating SQL text from AST
+//!
+//! This crate allows users to recover the original SQL text (with normalized
+//! whitespace and identifier capitalization), which is useful for tools that
+//! analyze and manipulate SQL.
+//!
+//! ```
+//! # use sqlparser::dialect::GenericDialect;
+//! # use sqlparser::parser::Parser;
+//! let sql = "SELECT a FROM table_1";
+//!
+//! // parse to a Vec<Statement>
+//! let ast = Parser::parse_sql(&GenericDialect, sql).unwrap();
+//!
+//! // The original SQL text can be generated from the AST
+//! assert_eq!(ast[0].to_string(), sql);
+//! ```
+//!
 //! [sqlparser crates.io page]: https://crates.io/crates/sqlparser
 //! [`Parser::parse_sql`]: crate::parser::Parser::parse_sql
 //! [`Parser::new`]: crate::parser::Parser::new

src/test_utils.rs

@@ -102,6 +102,11 @@ impl TestedDialects {
     /// Ensures that `sql` parses as a single [Statement] for all tested
     /// dialects.
     ///
+    /// In general, the canonical SQL should be the same (see crate
+    /// documentation for rationale) and you should prefer the `verified_`
+    /// variants in testing, such as  [`verified_statement`] or
+    /// [`verified_query`].
+    ///
     /// If `canonical` is non empty,this function additionally asserts
     /// that:
     ///