Add some more documentation

Author: alamb

src/ast/spans.rs

@@ -37,8 +37,25 @@ fn union_spans<I: Iterator<Item = Span>>(iter: I) -> Span {
 /// on which nodes are missing spans.
 ///
 /// [this ticket]: https://github.com/apache/datafusion-sqlparser-rs/issues/1548
+///
+/// # Example
+/// ```
+/// # use sqlparser::parser::{Parser, ParserError};
+/// # use sqlparser::ast::Spanned;
+/// # use sqlparser::dialect::GenericDialect;
+/// # fn main() -> Result<(), ParserError> {
+/// let dialect = GenericDialect {};
+/// let statements = Parser::new(&dialect)
+///   .try_with_sql("SELECT * FROM table_1")?
+///   .parse_statements()?;
+/// let span = statements[0].span();
+/// assert!(span.
+/// # Ok(())
+/// # }
+/// ```
+///
 pub trait Spanned {
-    /// Return the the source [`Span`] for this AST node, by recursively
+    /// Return the source [`Span`] for this AST node, by recursively
     /// combining the spans of its children.
     fn span(&self) -> Span;
 }

src/tokenizer.rs

@@ -422,13 +422,35 @@ impl fmt::Display for Whitespace {
 }
 
 /// Location in input string
+///
+/// # Create an "empty" (unknown) `Location`
+/// ```
+/// # use sqlparser::tokenizer::Location;
+/// let location = Location::empty();
+/// ```
+///
+/// # Create a `Location` from a line and column
+/// ```
+/// # use sqlparser::tokenizer::Location;
+/// let location = Location::new(1, 1);
+/// ```
+///
+/// # Create a `Location` from a pair
+/// ```
+/// # use sqlparser::tokenizer::Location;
+/// let location = Location::from((1, 1));
+/// ```
 #[derive(Eq, PartialEq, Hash, Clone, Copy, Ord, PartialOrd)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(feature = "visitor", derive(Visit, VisitMut))]
 pub struct Location {
-    /// Line number, starting from 1
+    /// Line number, starting from 1.
+    ///
+    /// Line 0 is used for empty spans
     pub line: u64,
-    /// Line column, starting from 1
+    /// Line column, starting from 1.
+    ///
+    /// Column 0 is used for empty spans
     pub column: u64,
 }
 
@@ -448,10 +470,24 @@ impl fmt::Debug for Location {
 }
 
 impl Location {
-    pub fn of(line: u64, column: u64) -> Self {
+    /// Return an "empty" / unknown location
+    pub fn empty() -> Self {
+        Self { line: 0, column: 0 }
+    }
+
+    /// Create a new `Location` for a given line and column
+    pub fn new(line: u64, column: u64) -> Self {
         Self { line, column }
     }
 
+    /// Create a new location for a given line and column
+    ///
+    // TODO: remove / deprecate in favor of` `new` for consistency?
+    pub fn of(line: u64, column: u64) -> Self {
+        Self::new(line, column)
+    }
+
+    /// Combine self and `end` into a new `Span`
     pub fn span_to(self, end: Self) -> Span {
         Span { start: self, end }
     }