[arrow-datafusion] branch main updated: Minor: Improve doc comments to datafusion-sql (#7318)

[alamb]

This is an automated email from the ASF dual-hosted git repository.

alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-datafusion.git


The following commit(s) were added to refs/heads/main by this push:
     new f7e784cbba Minor: Improve doc comments to datafusion-sql (#7318)
f7e784cbba is described below

commit f7e784cbba00040d56e3ac5f257b4412bc2252da
Author: Andrew Lamb <and...@nerdnetworks.org>
AuthorDate: Fri Aug 18 09:30:11 2023 -0400

    Minor: Improve doc comments to datafusion-sql (#7318)
    
    * Minor: Improve doc comments to datafusion-sql
    
    * Update datafusion/sql/src/lib.rs
    
    Co-authored-by: Liang-Chi Hsieh <vii...@gmail.com>
    
    ---------
    
    Co-authored-by: Liang-Chi Hsieh <vii...@gmail.com>
---
 datafusion/sql/src/lib.rs     | 14 ++++++++++++--
 datafusion/sql/src/parser.rs  | 19 ++++++++++++++-----
 datafusion/sql/src/planner.rs |  2 +-
 3 files changed, 27 insertions(+), 8 deletions(-)

diff --git a/datafusion/sql/src/lib.rs b/datafusion/sql/src/lib.rs
index c0c1a4ac91..d805f61397 100644
--- a/datafusion/sql/src/lib.rs
+++ b/datafusion/sql/src/lib.rs
@@ -15,8 +15,18 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! This module provides a SQL parser that translates SQL queries into an 
abstract syntax
-//! tree (AST), and a SQL query planner that creates a logical plan from the 
AST.
+//! This module provides:
+//!
+//! 1. A SQL parser, [`DFParser`], that translates SQL query text into
+//! an abstract syntax tree (AST), [`Statement`].
+//!
+//! 2. A SQL query planner [`SqlToRel`] that creates [`LogicalPlan`]s
+//! from [`Statement`]s.
+//!
+//! [`DFParser`]: parser::DFParser
+//! [`Statement`]: parser::Statement
+//! [`SqlToRel`]: planner::SqlToRel
+//! [`LogicalPlan`]: datafusion_expr::logical_plan::LogicalPlan
 
 mod expr;
 pub mod parser;
diff --git a/datafusion/sql/src/parser.rs b/datafusion/sql/src/parser.rs
index 6bd6ffded2..0d2d601a68 100644
--- a/datafusion/sql/src/parser.rs
+++ b/datafusion/sql/src/parser.rs
@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! DataFusion SQL Parser based on [`sqlparser`]
+//! [`DFParser`]: DataFusion SQL Parser based on [`sqlparser`]
 
 use datafusion_common::parsers::CompressionTypeVariant;
 use sqlparser::ast::{OrderByExpr, Query, Value};
@@ -191,9 +191,13 @@ pub struct DescribeTableStmt {
     pub table_name: ObjectName,
 }
 
-/// DataFusion Statement representations.
+/// DataFusion SQL Statement.
 ///
-/// Tokens parsed by [`DFParser`] are converted into these values.
+/// This can either be a [`Statement`] from [`sqlparser`] from a
+/// standard SQL dialect, or a DataFusion extension such as `CREATE
+/// EXTERAL TABLE`. See [`DFParser`] for more information.
+///
+/// [`Statement`]: sqlparser::ast::Statement
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum Statement {
     /// ANSI SQL AST node (from sqlparser-rs)
@@ -219,8 +223,13 @@ impl fmt::Display for Statement {
 
 /// DataFusion SQL Parser based on [`sqlparser`]
 ///
-/// This parser handles DataFusion specific statements, delegating to
-/// [`Parser`](sqlparser::parser::Parser) for other SQL statements.
+/// Parses DataFusion's SQL dialect, often delegating to [`sqlparser`]'s
+/// [`Parser`](sqlparser::parser::Parser).
+///
+/// DataFusion mostly follows existing SQL dialects via
+/// `sqlparser`. However, certain statements such as `COPY` and
+/// `CREATE EXTERNAL TABLE` have special syntax in DataFusion. See
+/// [`Statement`] for a list of this special syntax
 pub struct DFParser<'a> {
     parser: Parser<'a>,
 }
diff --git a/datafusion/sql/src/planner.rs b/datafusion/sql/src/planner.rs
index 1bf1ffbaef..bda6a3d40f 100644
--- a/datafusion/sql/src/planner.rs
+++ b/datafusion/sql/src/planner.rs
@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! SQL Query Planner (produces logical plan from SQL AST)
+//! [`SqlToRel`]: SQL Query Planner (produces [`LogicalPlan`] from SQL AST)
 use std::collections::HashMap;
 use std::sync::Arc;
 use std::vec;