Update comments / docs for Spanned
#1549
Conversation
alamb
force-pushed
the
alamb/doc_sql_parser
branch
from
2092351
to
bb7ad71
Compare
| @@ -1,52 +0,0 @@ | |||
|
|
|||
There was a problem hiding this comment.
This content is great. However, I think it may be hard to find given it is in a separate file
I moved the content into two places:
- docs in lib.rs for stuff that is relevant to users
- The [EPIC] Complete Span (source location) information / feature #1548 for things that are related to contributors
I think that will make it more likely the documentation can be discovered
alamb
force-pushed
the
alamb/doc_sql_parser
branch
from
d08e6ec
to
ec24d26
Compare
| 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 |
There was a problem hiding this comment.
drive by clarification
| @@ -80,3 +128,9 @@ impl From<TokenWithLocation> for AttachedToken { | |||
| AttachedToken(value) | |||
| } | |||
| } | |||
|
|
|||
| impl From<AttachedToken> for TokenWithLocation { | |||
There was a problem hiding this comment.
this seemed to be an obvious gap so I just added it to avoid a papercut
| /// | ||
| /// [this ticket]: https://github.com/apache/datafusion-sqlparser-rs/issues/1548 | ||
| /// | ||
| /// # Example |
There was a problem hiding this comment.
I felt an example will help people understand how to use the Spans
| //! [sqlparser crates.io page]: https://crates.io/crates/sqlparser | ||
| //! [`Parser::parse_sql`]: crate::parser::Parser::parse_sql | ||
| //! [`Parser::new`]: crate::parser::Parser::new | ||
| //! [`AST`]: crate::ast | ||
| //! [`ast`]: crate::ast | ||
| //! [`Dialect`]: crate::dialect::Dialect | ||
| //! | ||
| //! # Source Spans |
There was a problem hiding this comment.
This content is largely migrated from docs/source_spans.md
| #[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. |
There was a problem hiding this comment.
/// means these comments show up in docs
| /// Create a new location for a given line and column | ||
| /// | ||
| /// Alias for [`Self::new`] | ||
| // TODO: remove / deprecate in favor of` `new` for consistency? |
There was a problem hiding this comment.
I found the Location::of API kind of confusing -- I would expect that creating a new Rust object would be done via ::new() so I added a new()
I am thinking perhaps we can deprecate Location::of maybe to help downstream users
| @@ -21,21 +21,51 @@ use super::{ | |||
|
|
|||
| /// Given an iterator of spans, return the [Span::union] of all spans. | |||
| fn union_spans<I: Iterator<Item = Span>>(iter: I) -> Span { | |||
| iter.reduce(|acc, item| acc.union(&item)) | |||
| .unwrap_or(Span::empty()) | |||
| Span::union_iter(iter) | |||
There was a problem hiding this comment.
this was useful enough I felt making it a method in Span with more documentation and examples would make it easier to find
| /// Span::union_iter(spans), | ||
| /// Span::new(Location::new(1, 1), Location::new(4, 2)) | ||
| /// ); | ||
| pub fn union_iter<I: IntoIterator<Item = Span>>(iter: I) -> Span { |
There was a problem hiding this comment.
This was a private function and I thought it was useful enough it should be its own API and have an example, so I pulled it into a method
I took a pass over the code in #1435 and found some places
I thought adding some more documentation would be helpful.
Changes
Follow on work (tickets)
TokenWithLocationtoTokenWithSpan, in backwards compatible way #1562