Document round trip ability (apache#1052)

Author: alamb

README.md

@@ -59,6 +59,28 @@ This crate avoids semantic analysis because it varies drastically
 between dialects and implementations. If you want to do semantic
 analysis, feel free to use this project as a base.
 
+## Preserves Syntax Round Trip 
+
+This crate allows users to recover the original SQL text (with normalized
+whitespace and keyword capitalization), which is useful for tools that
+analyze and manipulate SQL.
+
+This means that other than whitespace and the capitalization of keywords, the
+following should hold true for all SQL:
+
+```rust
+// Parse SQL
+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);
+```
+
+There are still some cases in this crate where different SQL with seemingly
+similar semantics are represented with the same AST. We welcome PRs to fix such
+issues and distinguish different syntaxes in the AST.
+
+
 ## SQL compliance
 
 SQL was first standardized in 1987, and revisions of the standard have been

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:
     ///