Fix cargo docs / warnings and add CI check (#777)

* Fix all rustdoc links

* Add docs CI check

* workflow

* test error

* fix yml

* fix yml

* Revert "test error"

This reverts commit 96a40a88a3.

* fix

* more

.github/workflows/rust.yml

@@ -35,6 +35,16 @@ jobs:
       - uses: actions/checkout@master
       - run: cargo check --all-targets --all-features
 
+  docs:
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: "-Dwarnings"
+    steps:
+      - name: Set up Rust
+        uses: hecrj/setup-rust-action@v1
+      - uses: actions/checkout@master
+      - run: cargo doc --document-private-items --no-deps --workspace --all-features
+
   compile-no-std:
     runs-on: ubuntu-latest
     steps:

src/ast/ddl.rs

@@ -10,7 +10,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! AST types specific to CREATE/ALTER variants of [Statement]
+//! AST types specific to CREATE/ALTER variants of [`Statement`](crate::ast::Statement)
 //! (commonly referred to as Data Definition Language, or DDL)
 
 #[cfg(not(feature = "std"))]
@@ -325,6 +325,7 @@ pub enum TableConstraint {
     /// ```
     ///
     /// [1]: https://dev.mysql.com/doc/refman/8.0/en/fulltext-natural-language.html
+    /// [2]: https://dev.mysql.com/doc/refman/8.0/en/spatial-types.html
     FulltextOrSpatial {
         /// Whether this is a `FULLTEXT` (true) or `SPATIAL` (false) definition.
         fulltext: bool,

src/ast/mod.rs

@@ -372,39 +372,52 @@ pub enum Expr {
         timestamp: Box<Expr>,
         time_zone: String,
     },
+    /// ```sql
     /// EXTRACT(DateTimeField FROM <expr>)
+    /// ```
     Extract {
         field: DateTimeField,
         expr: Box<Expr>,
     },
+    /// ```sql
     /// CEIL(<expr> [TO DateTimeField])
+    /// ```
     Ceil {
         expr: Box<Expr>,
         field: DateTimeField,
     },
+    /// ```sql
     /// FLOOR(<expr> [TO DateTimeField])
+    /// ```
     Floor {
         expr: Box<Expr>,
         field: DateTimeField,
     },
+    /// ```sql
     /// POSITION(<expr> in <expr>)
+    /// ```
     Position { expr: Box<Expr>, r#in: Box<Expr> },
+    /// ```sql
     /// SUBSTRING(<expr> [FROM <expr>] [FOR <expr>])
+    /// ```
     Substring {
         expr: Box<Expr>,
         substring_from: Option<Box<Expr>>,
         substring_for: Option<Box<Expr>>,
     },
-    /// TRIM([BOTH | LEADING | TRAILING] [<expr> FROM] <expr>)\
+    /// ```sql
-    /// Or\
+    /// TRIM([BOTH | LEADING | TRAILING] [<expr> FROM] <expr>)
     /// TRIM(<expr>)
+    /// ```
     Trim {
         expr: Box<Expr>,
         // ([BOTH | LEADING | TRAILING]
         trim_where: Option<TrimWhereField>,
         trim_what: Option<Box<Expr>>,
     },
+    /// ```sql
     /// OVERLAY(<expr> PLACING <expr> FROM <expr>[ FOR <expr> ]
+    /// ```
     Overlay {
         expr: Box<Expr>,
         overlay_what: Box<Expr>,
@@ -426,7 +439,7 @@ pub enum Expr {
     TypedString { data_type: DataType, value: String },
     /// Access a map-like object by field (e.g. `column['field']` or `column[4]`
     /// Note that depending on the dialect, struct like accesses may be
-    /// parsed as [`ArrayIndex`] or [`MapAccess`]
+    /// parsed as [`ArrayIndex`](Self::ArrayIndex) or [`MapAccess`](Self::MapAccess)
     /// <https://clickhouse.com/docs/en/sql-reference/data-types/map/>
     MapAccess { column: Box<Expr>, keys: Vec<Expr> },
     /// Scalar function call e.g. `LEFT(foo, 5)`
@@ -490,7 +503,7 @@ pub enum Expr {
     /// `MySQL` specific text search function [(1)].
     ///
     /// Syntax:
-    /// ```text
+    /// ```sql
     /// MARCH (<col>, <col>, ...) AGAINST (<expr> [<search modifier>])
     ///
     /// <col> = CompoundIdentifier
@@ -956,9 +969,9 @@ pub struct WindowFrame {
 }
 
 impl Default for WindowFrame {
-    /// returns default value for window frame
+    /// Returns default value for window frame
     ///
-    /// see https://www.sqlite.org/windowfunctions.html#frame_specifications
+    /// See [this page](https://www.sqlite.org/windowfunctions.html#frame_specifications) for more details.
     fn default() -> Self {
         Self {
             units: WindowFrameUnits::Range,
@@ -1365,7 +1378,9 @@ pub enum Statement {
         /// Role name. If NONE is specified, then the current role name is removed.
         role_name: Option<Ident>,
     },
+    /// ```sql
     /// SET <variable>
+    /// ```
     ///
     /// Note: this is not a standard SQL statement, but it is supported by at
     /// least MySQL and PostgreSQL. Not all MySQL-specific syntatic forms are
@@ -1376,10 +1391,12 @@ pub enum Statement {
         variable: ObjectName,
         value: Vec<Expr>,
     },
+    /// ```sql
     /// SET TIME ZONE <value>
+    /// ```
     ///
     /// Note: this is a PostgreSQL-specific statements
-    /// SET TIME ZONE <value> is an alias for SET timezone TO <value> in PostgreSQL
+    /// `SET TIME ZONE <value>` is an alias for `SET timezone TO <value>` in PostgreSQL
     SetTimeZone { local: bool, value: Expr },
     /// SET NAMES 'charset_name' [COLLATE 'collation_name']
     ///
@@ -1396,7 +1413,9 @@ pub enum Statement {
     ///
     /// Note: this is a Presto-specific statement.
     ShowFunctions { filter: Option<ShowStatementFilter> },
+    /// ```sql
     /// SHOW <variable>
+    /// ```
     ///
     /// Note: this is a PostgreSQL-specific statement.
     ShowVariable { variable: Vec<Ident> },
@@ -1471,10 +1490,13 @@ pub enum Statement {
         location: Option<String>,
         managed_location: Option<String>,
     },
+    /// ```sql
     /// CREATE FUNCTION
+    /// ```
     ///
-    /// Hive: https://cwiki.apache.org/confluence/display/hive/languagemanual+ddl#LanguageManualDDL-Create/Drop/ReloadFunction
+    /// Supported variants:
-    /// Postgres: https://www.postgresql.org/docs/15/sql-createfunction.html
+    /// 1. [Hive](https://cwiki.apache.org/confluence/display/hive/languagemanual+ddl#LanguageManualDDL-Create/Drop/ReloadFunction)
+    /// 2. [Postgres](https://www.postgresql.org/docs/15/sql-createfunction.html)
     CreateFunction {
         or_replace: bool,
         temporary: bool,
@@ -1567,8 +1589,11 @@ pub enum Statement {
         // Specifies the actions to perform when values match or do not match.
         clauses: Vec<MergeClause>,
     },
-    /// CACHE [ FLAG ] TABLE <table_name> [ OPTIONS('K1' = 'V1', 'K2' = V2) ] [ AS ] [ <query> ]
+    /// `CACHE [ FLAG ] TABLE <table_name> [ OPTIONS('K1' = 'V1', 'K2' = V2) ] [ AS ] [ <query> ]`.
-    /// Based on Spark SQL,see <https://docs.databricks.com/spark/latest/spark-sql/language-manual/sql-ref-syntax-aux-cache-cache-table.html>
+    ///
+    /// See [Spark SQL docs] for more details.
+    ///
+    /// [Spark SQL docs]: https://docs.databricks.com/spark/latest/spark-sql/language-manual/sql-ref-syntax-aux-cache-cache-table.html
     Cache {
         /// Table flag
         table_flag: Option<ObjectName>,
@@ -2707,9 +2732,11 @@ impl fmt::Display for Statement {
 }
 
 /// Can use to describe options in create sequence or table column type identity
+/// ```sql
 /// [ INCREMENT [ BY ] increment ]
 ///     [ MINVALUE minvalue | NO MINVALUE ] [ MAXVALUE maxvalue | NO MAXVALUE ]
 ///     [ START [ WITH ] start ] [ CACHE cache ] [ [ NO ] CYCLE ]
+/// ```
 #[derive(Debug, Clone, PartialEq, PartialOrd, Eq, Ord, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(feature = "visitor", derive(Visit))]
@@ -3540,7 +3567,8 @@ impl fmt::Display for ShowStatementFilter {
 
 /// Sqlite specific syntax
 ///
-/// https://sqlite.org/lang_conflict.html
+/// See [Sqlite documentation](https://sqlite.org/lang_conflict.html)
+/// for more details.
 #[derive(Debug, Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(feature = "visitor", derive(Visit))]
@@ -3979,7 +4007,10 @@ impl fmt::Display for FunctionDefinition {
     }
 }
 
-/// Postgres: https://www.postgresql.org/docs/15/sql-createfunction.html
+/// Postgres specific feature.
+///
+/// See [Postgresdocs](https://www.postgresql.org/docs/15/sql-createfunction.html)
+/// for more details
 #[derive(Debug, Default, Clone, PartialEq, PartialOrd, Eq, Ord, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(feature = "visitor", derive(Visit))]

src/ast/query.rs

@@ -529,6 +529,7 @@ pub enum TableFactor {
         expr: Expr,
         alias: Option<TableAlias>,
     },
+    /// ```sql
     /// SELECT * FROM UNNEST ([10,20,30]) as numbers WITH OFFSET;
     /// +---------+--------+
     /// | numbers | offset |
@@ -537,6 +538,7 @@ pub enum TableFactor {
     /// | 20      | 1      |
     /// | 30      | 2      |
     /// +---------+--------+
+    /// ```
     UNNEST {
         alias: Option<TableAlias>,
         array_expr: Box<Expr>,

src/ast/value.rs

@@ -38,7 +38,8 @@ pub enum Value {
     // $<tag_name>$string value$<tag_name>$ (postgres syntax)
     DollarQuotedString(DollarQuotedString),
     /// e'string value' (postgres extension)
-    /// <https://www.postgresql.org/docs/8.3/sql-syntax-lexical.html#SQL-SYNTAX-STRINGS
+    /// See [Postgres docs](https://www.postgresql.org/docs/8.3/sql-syntax-lexical.html#SQL-SYNTAX-STRINGS)
+    /// for more details.
     EscapedStringLiteral(String),
     /// N'string value'
     NationalStringLiteral(String),

src/dialect/mod.rs

@@ -71,9 +71,10 @@ pub trait Dialect: Debug + Any {
     fn supports_filter_during_aggregation(&self) -> bool {
         false
     }
-    /// Returns true if the dialect supports ARRAY_AGG() [WITHIN GROUP (ORDER BY)] expressions.
+    /// Returns true if the dialect supports `ARRAY_AGG() [WITHIN GROUP (ORDER BY)]` expressions.
-    /// Otherwise, the dialect should expect an `ORDER BY` without the `WITHIN GROUP` clause, e.g. `ANSI` [(1)].
+    /// Otherwise, the dialect should expect an `ORDER BY` without the `WITHIN GROUP` clause, e.g. [`ANSI`]
-    /// [(1)]: https://jakewheat.github.io/sql-overview/sql-2016-foundation-grammar.html#array-aggregate-function
+    ///
+    /// [`ANSI`]: https://jakewheat.github.io/sql-overview/sql-2016-foundation-grammar.html#array-aggregate-function
     fn supports_within_after_array_aggregation(&self) -> bool {
         false
     }

src/keywords.rs

@@ -11,9 +11,7 @@
 // limitations under the License.
 
 //! This module defines
-//! 1) a list of constants for every keyword that
+//! 1) a list of constants for every keyword
-//! can appear in [Word::keyword]:
-//!    pub const KEYWORD = "KEYWORD"
 //! 2) an `ALL_KEYWORDS` array with every keyword in it
 //!     This is not a list of *reserved* keywords: some of these can be
 //!     parsed as identifiers if the parser decides so. This means that

src/parser.rs

@@ -1181,8 +1181,10 @@ impl<'a> Parser<'a> {
         })
     }
 
-    /// TRIM ([WHERE] ['text' FROM] 'text')\
+    /// ```sql
+    /// TRIM ([WHERE] ['text' FROM] 'text')
     /// TRIM ('text')
+    /// ```
     pub fn parse_trim_expr(&mut self) -> Result<Expr, ParserError> {
         self.expect_token(&Token::LParen)?;
         let mut trim_where = None;
@@ -2984,8 +2986,10 @@ impl<'a> Parser<'a> {
         })
     }
 
+    /// ```sql
     /// DROP FUNCTION [ IF EXISTS ] name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] [, ...]
     /// [ CASCADE | RESTRICT ]
+    /// ```
     fn parse_drop_function(&mut self) -> Result<Statement, ParserError> {
         let if_exists = self.parse_keywords(&[Keyword::IF, Keyword::EXISTS]);
         let func_desc = self.parse_comma_separated(Parser::parse_drop_function_desc)?;
@@ -3019,8 +3023,10 @@ impl<'a> Parser<'a> {
         Ok(DropFunctionDesc { name, args })
     }
 
+    /// ```sql
     /// DECLARE name [ BINARY ] [ ASENSITIVE | INSENSITIVE ] [ [ NO ] SCROLL ]
-    //     CURSOR [ { WITH | WITHOUT } HOLD ] FOR query
+    ///     CURSOR [ { WITH | WITHOUT } HOLD ] FOR query
+    /// ```
     pub fn parse_declare(&mut self) -> Result<Statement, ParserError> {
         let name = self.parse_identifier()?;
 
@@ -4822,7 +4828,7 @@ impl<'a> Parser<'a> {
 
     /// Parse a "query body", which is an expression with roughly the
     /// following grammar:
-    /// ```text
+    /// ```sql
     ///   query_body ::= restricted_select | '(' subquery ')' | set_operation
     ///   restricted_select ::= 'SELECT' [expr_list] [ from ] [ where ] [ groupby_having ]
     ///   subquery ::= query_body [ order_by_limit ]
@@ -6130,7 +6136,7 @@ impl<'a> Parser<'a> {
     }
 
     /// Parse a TOP clause, MSSQL equivalent of LIMIT,
-    /// that follows after SELECT [DISTINCT].
+    /// that follows after `SELECT [DISTINCT]`.
     pub fn parse_top(&mut self) -> Result<Top, ParserError> {
         let quantity = if self.consume_token(&Token::LParen) {
             let quantity = self.parse_expr()?;
@@ -6449,8 +6455,11 @@ impl<'a> Parser<'a> {
         })
     }
 
-    /// https://www.postgresql.org/docs/current/sql-createsequence.html
+    /// ```sql
     /// CREATE [ { TEMPORARY | TEMP } ] SEQUENCE [ IF NOT EXISTS ] <sequence_name>
+    /// ```
+    ///
+    /// See [Postgres docs](https://www.postgresql.org/docs/current/sql-createsequence.html) for more details.
     pub fn parse_create_sequence(&mut self, temporary: bool) -> Result<Statement, ParserError> {
         //[ IF NOT EXISTS ]
         let if_not_exists = self.parse_keywords(&[Keyword::IF, Keyword::NOT, Keyword::EXISTS]);