Add docstrings for Dialects, update README (#1016)

src/dialect/ansi.rs

@@ -12,6 +12,7 @@
 
 use crate::dialect::Dialect;
 
+/// A [`Dialect`] for [ANSI SQL](https://en.wikipedia.org/wiki/SQL:2011).
 #[derive(Debug)]
 pub struct AnsiDialect {}
 

src/dialect/bigquery.rs

@@ -12,6 +12,7 @@
 
 use crate::dialect::Dialect;
 
+/// A [`Dialect`] for [Google Bigquery](https://cloud.google.com/bigquery/)
 #[derive(Debug, Default)]
 pub struct BigQueryDialect;
 

src/dialect/clickhouse.rs

@@ -12,6 +12,7 @@
 
 use crate::dialect::Dialect;
 
+// A [`Dialect`] for [ClickHouse](https://clickhouse.com/).
 #[derive(Debug)]
 pub struct ClickHouseDialect {}
 

src/dialect/duckdb.rs

@@ -12,6 +12,7 @@
 
 use crate::dialect::Dialect;
 
+/// A [`Dialect`] for [DuckDB](https://duckdb.org/)
 #[derive(Debug, Default)]
 pub struct DuckDbDialect;
 

src/dialect/generic.rs

@@ -12,6 +12,8 @@
 
 use crate::dialect::Dialect;
 
+/// A permissive, general purpose [`Dialect`], which parses a wide variety of SQL
+/// statements, from many different dialects.
 #[derive(Debug, Default)]
 pub struct GenericDialect;
 

src/dialect/hive.rs

@@ -12,6 +12,7 @@
 
 use crate::dialect::Dialect;
 
+/// A [`Dialect`] for [Hive](https://hive.apache.org/).
 #[derive(Debug)]
 pub struct HiveDialect {}
 

src/dialect/mod.rs

@@ -64,6 +64,9 @@ macro_rules! dialect_of {
 /// custom extensions or various historical reasons. This trait
 /// encapsulates the parsing differences between dialects.
 ///
+/// [`GenericDialect`] is the most permissive dialect, and parses the union of
+/// all the other dialects, when there is no ambiguity.
+///
 /// # Examples
 /// Most users create a [`Dialect`] directly, as shown on the [module
 /// level documentation]:

src/dialect/mssql.rs

@@ -12,7 +12,7 @@
 
 use crate::dialect::Dialect;
 
-// [Microsoft SQL Server](https://www.microsoft.com/en-us/sql-server/) dialect
+/// A [`Dialect`] for [Microsoft SQL Server](https://www.microsoft.com/en-us/sql-server/)
 #[derive(Debug)]
 pub struct MsSqlDialect {}
 

src/dialect/mysql.rs

@@ -19,7 +19,7 @@ use crate::{
     keywords::Keyword,
 };
 
-/// [MySQL](https://www.mysql.com/)
+/// A [`Dialect`] for [MySQL](https://www.mysql.com/)
 #[derive(Debug)]
 pub struct MySqlDialect {}
 

src/dialect/postgresql.rs

@@ -16,6 +16,7 @@ use crate::keywords::Keyword;
 use crate::parser::{Parser, ParserError};
 use crate::tokenizer::Token;
 
+/// A [`Dialect`] for [PostgreSQL](https://www.postgresql.org/)
 #[derive(Debug)]
 pub struct PostgreSqlDialect {}
 

src/dialect/redshift.rs

@@ -16,6 +16,7 @@ use core::str::Chars;
 
 use super::PostgreSqlDialect;
 
+/// A [`Dialect`] for [RedShift](https://aws.amazon.com/redshift/)
 #[derive(Debug)]
 pub struct RedshiftSqlDialect {}
 

src/dialect/snowflake.rs

@@ -28,6 +28,7 @@ use alloc::vec::Vec;
 #[cfg(not(feature = "std"))]
 use alloc::{format, vec};
 
+/// A [`Dialect`] for [Snowflake](https://www.snowflake.com/)
 #[derive(Debug, Default)]
 pub struct SnowflakeDialect;
 

src/dialect/sqlite.rs

@@ -15,6 +15,7 @@ use crate::dialect::Dialect;
 use crate::keywords::Keyword;
 use crate::parser::{Parser, ParserError};
 
+/// A [`Dialect`] for [SQLite](https://www.sqlite.org)
 #[derive(Debug)]
 pub struct SQLiteDialect {}