docs on span

Author: alamb

README.md

@@ -128,9 +128,9 @@ SQL was first standardized in 1987, and revisions of the standard have been
 published regularly since. Most revisions have added significant new features to
 the language, and as a result no database claims to support the full breadth of
 features. This parser currently supports most of the SQL-92 syntax, plus some
-syntax from newer versions that have been explicitly requested, plus some MSSQL,
-PostgreSQL, and other dialect-specific syntax. Whenever possible, the [online
-SQL:2016 grammar][sql-2016-grammar] is used to guide what syntax to accept.
+syntax from newer versions that have been explicitly requested, plus various
+other dialect-specific syntax. Whenever possible, the [online SQL:2016
+grammar][sql-2016-grammar] is used to guide what syntax to accept.
 
 Unfortunately, stating anything more specific about compliance is difficult.
 There is no publicly available test suite that can assess compliance

src/ast/spans.rs

@@ -27,14 +27,18 @@ fn union_spans<I: Iterator<Item = Span>>(iter: I) -> Span {
 
 /// A trait for AST nodes that have a source span for use in diagnostics.
 ///
-/// Source spans are not guaranteed to be entirely accurate. They may
-/// be missing keywords or other tokens. Some nodes may not have a computable
-/// span at all, in which case they return [`Span::empty()`].
+/// Note: Source spans are likely not currently entirely accurate. They may
+/// 1. Be missing keywords or other tokens.
+/// 2. Not have span information at all, in which case they return [`Span::empty()`].
 ///
-/// Some impl blocks may contain doc comments with information
+/// See [this ticket] for more information.
+///
+/// Note Some impl blocks may contain doc comments with information
 /// on which nodes are missing spans.
+///
+/// [this ticket]: https://github.com/apache/datafusion-sqlparser-rs/issues/1548
 pub trait Spanned {
-    /// Compute the source span for this AST node, by recursively
+    /// Return the the source [`Span`] for this AST node, by recursively
     /// combining the spans of its children.
     fn span(&self) -> Span;
 }

src/lib.rs

@@ -25,6 +25,9 @@
 //! 1. [`Parser::parse_sql`] and [`Parser::new`] for the Parsing API
 //! 2. [`ast`] for the AST structure
 //! 3. [`Dialect`] for supported SQL dialects
+//! 4. [`Spanned`] for source text locations
+//!
+//! [`Spanned`]: ast::Spanned
 //!
 //! # Example parsing SQL text
 //!