document the new feature

Author: lovasoa

src/ast/mod.rs

@@ -4207,6 +4207,28 @@ impl fmt::Display for RaisErrorOption {
 }
 
 impl fmt::Display for Statement {
+    /// Formats a SQL statement with support for pretty printing.
+    ///
+    /// When using the alternate flag (`{:#}`), the statement will be formatted with proper
+    /// indentation and line breaks. For example:
+    ///
+    /// ```
+    /// # use sqlparser::dialect::GenericDialect;
+    /// # use sqlparser::parser::Parser;
+    /// let sql = "SELECT a, b FROM table_1";
+    /// let ast = Parser::parse_sql(&GenericDialect, sql).unwrap();
+    ///
+    /// // Regular formatting
+    /// assert_eq!(format!("{}", ast[0]), "SELECT a, b FROM table_1");
+    ///
+    /// // Pretty printing
+    /// assert_eq!(format!("{:#}", ast[0]),
+    /// r#"SELECT
+    ///   a,
+    ///   b
+    /// FROM
+    ///   table_1"#);
+    /// ```
     // Clippy thinks this function is too complicated, but it is painful to
     // split up without extracting structs for each `Statement` variant.
     #[allow(clippy::cognitive_complexity)]

src/display_utils.rs

@@ -1,3 +1,9 @@
+//! Utilities for formatting SQL AST nodes with pretty printing support.
+//!
+//! The module provides formatters that implement the `Display` trait with support
+//! for both regular (`{}`) and pretty (`{:#}`) formatting modes. Pretty printing
+//! adds proper indentation and line breaks to make SQL statements more readable.
+
 use core::fmt::{self, Display, Write};
 
 /// A wrapper around a value that adds an indent to the value when displayed with {:#}.

src/lib.rs

@@ -64,6 +64,27 @@
 //! // The original SQL text can be generated from the AST
 //! assert_eq!(ast[0].to_string(), sql);
 //! ```
+//!
+//! # Pretty Printing
+//!
+//! SQL statements can be pretty-printed with proper indentation and line breaks using the alternate flag (`{:#}`):
+//!
+//! ```
+//! # use sqlparser::dialect::GenericDialect;
+//! # use sqlparser::parser::Parser;
+//! let sql = "SELECT a, b FROM table_1";
+//! let ast = Parser::parse_sql(&GenericDialect, sql).unwrap();
+//!
+//! // Pretty print with indentation and line breaks
+//! let pretty_sql = format!("{:#}", ast[0]);
+//! assert_eq!(pretty_sql, r#"
+//! SELECT
+//!   a,
+//!   b
+//! FROM
+//!   table_1
+//! "#.trim());
+//! ```
 //! [sqlparser crates.io page]: https://crates.io/crates/sqlparser
 //! [`Parser::parse_sql`]: crate::parser::Parser::parse_sql
 //! [`Parser::new`]: crate::parser::Parser::new