Skip to content

Commit b93d82d

Browse files
authored
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 96a40a8. * fix * more
1 parent 072ccc0 commit b93d82d

File tree

8 files changed

+79
-26
lines changed

8 files changed

+79
-26
lines changed

.github/workflows/rust.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,16 @@ jobs:
3535
- uses: actions/checkout@master
3636
- run: cargo check --all-targets --all-features
3737

38+
docs:
39+
runs-on: ubuntu-latest
40+
env:
41+
RUSTDOCFLAGS: "-Dwarnings"
42+
steps:
43+
- name: Set up Rust
44+
uses: hecrj/setup-rust-action@v1
45+
- uses: actions/checkout@master
46+
- run: cargo doc --document-private-items --no-deps --workspace --all-features
47+
3848
compile-no-std:
3949
runs-on: ubuntu-latest
4050
steps:

src/ast/ddl.rs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
// See the License for the specific language governing permissions and
1111
// limitations under the License.
1212

13-
//! AST types specific to CREATE/ALTER variants of [Statement]
13+
//! AST types specific to CREATE/ALTER variants of [`Statement`](crate::ast::Statement)
1414
//! (commonly referred to as Data Definition Language, or DDL)
1515
1616
#[cfg(not(feature = "std"))]
@@ -325,6 +325,7 @@ pub enum TableConstraint {
325325
/// ```
326326
///
327327
/// [1]: https://dev.mysql.com/doc/refman/8.0/en/fulltext-natural-language.html
328+
/// [2]: https://dev.mysql.com/doc/refman/8.0/en/spatial-types.html
328329
FulltextOrSpatial {
329330
/// Whether this is a `FULLTEXT` (true) or `SPATIAL` (false) definition.
330331
fulltext: bool,

src/ast/mod.rs

Lines changed: 44 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -372,39 +372,52 @@ pub enum Expr {
372372
timestamp: Box<Expr>,
373373
time_zone: String,
374374
},
375+
/// ```sql
375376
/// EXTRACT(DateTimeField FROM <expr>)
377+
/// ```
376378
Extract {
377379
field: DateTimeField,
378380
expr: Box<Expr>,
379381
},
382+
/// ```sql
380383
/// CEIL(<expr> [TO DateTimeField])
384+
/// ```
381385
Ceil {
382386
expr: Box<Expr>,
383387
field: DateTimeField,
384388
},
389+
/// ```sql
385390
/// FLOOR(<expr> [TO DateTimeField])
391+
/// ```
386392
Floor {
387393
expr: Box<Expr>,
388394
field: DateTimeField,
389395
},
396+
/// ```sql
390397
/// POSITION(<expr> in <expr>)
398+
/// ```
391399
Position { expr: Box<Expr>, r#in: Box<Expr> },
400+
/// ```sql
392401
/// SUBSTRING(<expr> [FROM <expr>] [FOR <expr>])
402+
/// ```
393403
Substring {
394404
expr: Box<Expr>,
395405
substring_from: Option<Box<Expr>>,
396406
substring_for: Option<Box<Expr>>,
397407
},
398-
/// TRIM([BOTH | LEADING | TRAILING] [<expr> FROM] <expr>)\
399-
/// Or\
408+
/// ```sql
409+
/// TRIM([BOTH | LEADING | TRAILING] [<expr> FROM] <expr>)
400410
/// TRIM(<expr>)
411+
/// ```
401412
Trim {
402413
expr: Box<Expr>,
403414
// ([BOTH | LEADING | TRAILING]
404415
trim_where: Option<TrimWhereField>,
405416
trim_what: Option<Box<Expr>>,
406417
},
418+
/// ```sql
407419
/// OVERLAY(<expr> PLACING <expr> FROM <expr>[ FOR <expr> ]
420+
/// ```
408421
Overlay {
409422
expr: Box<Expr>,
410423
overlay_what: Box<Expr>,
@@ -426,7 +439,7 @@ pub enum Expr {
426439
TypedString { data_type: DataType, value: String },
427440
/// Access a map-like object by field (e.g. `column['field']` or `column[4]`
428441
/// Note that depending on the dialect, struct like accesses may be
429-
/// parsed as [`ArrayIndex`] or [`MapAccess`]
442+
/// parsed as [`ArrayIndex`](Self::ArrayIndex) or [`MapAccess`](Self::MapAccess)
430443
/// <https://clickhouse.com/docs/en/sql-reference/data-types/map/>
431444
MapAccess { column: Box<Expr>, keys: Vec<Expr> },
432445
/// Scalar function call e.g. `LEFT(foo, 5)`
@@ -490,7 +503,7 @@ pub enum Expr {
490503
/// `MySQL` specific text search function [(1)].
491504
///
492505
/// Syntax:
493-
/// ```text
506+
/// ```sql
494507
/// MARCH (<col>, <col>, ...) AGAINST (<expr> [<search modifier>])
495508
///
496509
/// <col> = CompoundIdentifier
@@ -956,9 +969,9 @@ pub struct WindowFrame {
956969
}
957970

958971
impl Default for WindowFrame {
959-
/// returns default value for window frame
972+
/// Returns default value for window frame
960973
///
961-
/// see https://www.sqlite.org/windowfunctions.html#frame_specifications
974+
/// See [this page](https://www.sqlite.org/windowfunctions.html#frame_specifications) for more details.
962975
fn default() -> Self {
963976
Self {
964977
units: WindowFrameUnits::Range,
@@ -1365,7 +1378,9 @@ pub enum Statement {
13651378
/// Role name. If NONE is specified, then the current role name is removed.
13661379
role_name: Option<Ident>,
13671380
},
1381+
/// ```sql
13681382
/// SET <variable>
1383+
/// ```
13691384
///
13701385
/// Note: this is not a standard SQL statement, but it is supported by at
13711386
/// least MySQL and PostgreSQL. Not all MySQL-specific syntatic forms are
@@ -1376,10 +1391,12 @@ pub enum Statement {
13761391
variable: ObjectName,
13771392
value: Vec<Expr>,
13781393
},
1394+
/// ```sql
13791395
/// SET TIME ZONE <value>
1396+
/// ```
13801397
///
13811398
/// Note: this is a PostgreSQL-specific statements
1382-
/// SET TIME ZONE <value> is an alias for SET timezone TO <value> in PostgreSQL
1399+
/// `SET TIME ZONE <value>` is an alias for `SET timezone TO <value>` in PostgreSQL
13831400
SetTimeZone { local: bool, value: Expr },
13841401
/// SET NAMES 'charset_name' [COLLATE 'collation_name']
13851402
///
@@ -1396,7 +1413,9 @@ pub enum Statement {
13961413
///
13971414
/// Note: this is a Presto-specific statement.
13981415
ShowFunctions { filter: Option<ShowStatementFilter> },
1416+
/// ```sql
13991417
/// SHOW <variable>
1418+
/// ```
14001419
///
14011420
/// Note: this is a PostgreSQL-specific statement.
14021421
ShowVariable { variable: Vec<Ident> },
@@ -1471,10 +1490,13 @@ pub enum Statement {
14711490
location: Option<String>,
14721491
managed_location: Option<String>,
14731492
},
1493+
/// ```sql
14741494
/// CREATE FUNCTION
1495+
/// ```
14751496
///
1476-
/// Hive: https://cwiki.apache.org/confluence/display/hive/languagemanual+ddl#LanguageManualDDL-Create/Drop/ReloadFunction
1477-
/// Postgres: https://www.postgresql.org/docs/15/sql-createfunction.html
1497+
/// Supported variants:
1498+
/// 1. [Hive](https://cwiki.apache.org/confluence/display/hive/languagemanual+ddl#LanguageManualDDL-Create/Drop/ReloadFunction)
1499+
/// 2. [Postgres](https://www.postgresql.org/docs/15/sql-createfunction.html)
14781500
CreateFunction {
14791501
or_replace: bool,
14801502
temporary: bool,
@@ -1567,8 +1589,11 @@ pub enum Statement {
15671589
// Specifies the actions to perform when values match or do not match.
15681590
clauses: Vec<MergeClause>,
15691591
},
1570-
/// CACHE [ FLAG ] TABLE <table_name> [ OPTIONS('K1' = 'V1', 'K2' = V2) ] [ AS ] [ <query> ]
1571-
/// Based on Spark SQL,see <https://docs.databricks.com/spark/latest/spark-sql/language-manual/sql-ref-syntax-aux-cache-cache-table.html>
1592+
/// `CACHE [ FLAG ] TABLE <table_name> [ OPTIONS('K1' = 'V1', 'K2' = V2) ] [ AS ] [ <query> ]`.
1593+
///
1594+
/// See [Spark SQL docs] for more details.
1595+
///
1596+
/// [Spark SQL docs]: https://docs.databricks.com/spark/latest/spark-sql/language-manual/sql-ref-syntax-aux-cache-cache-table.html
15721597
Cache {
15731598
/// Table flag
15741599
table_flag: Option<ObjectName>,
@@ -2707,9 +2732,11 @@ impl fmt::Display for Statement {
27072732
}
27082733

27092734
/// Can use to describe options in create sequence or table column type identity
2735+
/// ```sql
27102736
/// [ INCREMENT [ BY ] increment ]
27112737
/// [ MINVALUE minvalue | NO MINVALUE ] [ MAXVALUE maxvalue | NO MAXVALUE ]
27122738
/// [ START [ WITH ] start ] [ CACHE cache ] [ [ NO ] CYCLE ]
2739+
/// ```
27132740
#[derive(Debug, Clone, PartialEq, PartialOrd, Eq, Ord, Hash)]
27142741
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
27152742
#[cfg_attr(feature = "visitor", derive(Visit))]
@@ -3540,7 +3567,8 @@ impl fmt::Display for ShowStatementFilter {
35403567

35413568
/// Sqlite specific syntax
35423569
///
3543-
/// https://sqlite.org/lang_conflict.html
3570+
/// See [Sqlite documentation](https://sqlite.org/lang_conflict.html)
3571+
/// for more details.
35443572
#[derive(Debug, Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Hash)]
35453573
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
35463574
#[cfg_attr(feature = "visitor", derive(Visit))]
@@ -3979,7 +4007,10 @@ impl fmt::Display for FunctionDefinition {
39794007
}
39804008
}
39814009

3982-
/// Postgres: https://www.postgresql.org/docs/15/sql-createfunction.html
4010+
/// Postgres specific feature.
4011+
///
4012+
/// See [Postgresdocs](https://www.postgresql.org/docs/15/sql-createfunction.html)
4013+
/// for more details
39834014
#[derive(Debug, Default, Clone, PartialEq, PartialOrd, Eq, Ord, Hash)]
39844015
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
39854016
#[cfg_attr(feature = "visitor", derive(Visit))]

src/ast/query.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -529,6 +529,7 @@ pub enum TableFactor {
529529
expr: Expr,
530530
alias: Option<TableAlias>,
531531
},
532+
/// ```sql
532533
/// SELECT * FROM UNNEST ([10,20,30]) as numbers WITH OFFSET;
533534
/// +---------+--------+
534535
/// | numbers | offset |
@@ -537,6 +538,7 @@ pub enum TableFactor {
537538
/// | 20 | 1 |
538539
/// | 30 | 2 |
539540
/// +---------+--------+
541+
/// ```
540542
UNNEST {
541543
alias: Option<TableAlias>,
542544
array_expr: Box<Expr>,

src/ast/value.rs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,8 @@ pub enum Value {
3838
// $<tag_name>$string value$<tag_name>$ (postgres syntax)
3939
DollarQuotedString(DollarQuotedString),
4040
/// e'string value' (postgres extension)
41-
/// <https://www.postgresql.org/docs/8.3/sql-syntax-lexical.html#SQL-SYNTAX-STRINGS
41+
/// See [Postgres docs](https://www.postgresql.org/docs/8.3/sql-syntax-lexical.html#SQL-SYNTAX-STRINGS)
42+
/// for more details.
4243
EscapedStringLiteral(String),
4344
/// N'string value'
4445
NationalStringLiteral(String),

src/dialect/mod.rs

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -71,9 +71,10 @@ pub trait Dialect: Debug + Any {
7171
fn supports_filter_during_aggregation(&self) -> bool {
7272
false
7373
}
74-
/// Returns true if the dialect supports ARRAY_AGG() [WITHIN GROUP (ORDER BY)] expressions.
75-
/// Otherwise, the dialect should expect an `ORDER BY` without the `WITHIN GROUP` clause, e.g. `ANSI` [(1)].
76-
/// [(1)]: https://jakewheat.github.io/sql-overview/sql-2016-foundation-grammar.html#array-aggregate-function
74+
/// Returns true if the dialect supports `ARRAY_AGG() [WITHIN GROUP (ORDER BY)]` expressions.
75+
/// Otherwise, the dialect should expect an `ORDER BY` without the `WITHIN GROUP` clause, e.g. [`ANSI`]
76+
///
77+
/// [`ANSI`]: https://jakewheat.github.io/sql-overview/sql-2016-foundation-grammar.html#array-aggregate-function
7778
fn supports_within_after_array_aggregation(&self) -> bool {
7879
false
7980
}

src/keywords.rs

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,7 @@
1111
// limitations under the License.
1212

1313
//! This module defines
14-
//! 1) a list of constants for every keyword that
15-
//! can appear in [Word::keyword]:
16-
//! pub const KEYWORD = "KEYWORD"
14+
//! 1) a list of constants for every keyword
1715
//! 2) an `ALL_KEYWORDS` array with every keyword in it
1816
//! This is not a list of *reserved* keywords: some of these can be
1917
//! parsed as identifiers if the parser decides so. This means that

src/parser.rs

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1181,8 +1181,10 @@ impl<'a> Parser<'a> {
11811181
})
11821182
}
11831183

1184-
/// TRIM ([WHERE] ['text' FROM] 'text')\
1184+
/// ```sql
1185+
/// TRIM ([WHERE] ['text' FROM] 'text')
11851186
/// TRIM ('text')
1187+
/// ```
11861188
pub fn parse_trim_expr(&mut self) -> Result<Expr, ParserError> {
11871189
self.expect_token(&Token::LParen)?;
11881190
let mut trim_where = None;
@@ -2984,8 +2986,10 @@ impl<'a> Parser<'a> {
29842986
})
29852987
}
29862988

2989+
/// ```sql
29872990
/// DROP FUNCTION [ IF EXISTS ] name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] [, ...]
29882991
/// [ CASCADE | RESTRICT ]
2992+
/// ```
29892993
fn parse_drop_function(&mut self) -> Result<Statement, ParserError> {
29902994
let if_exists = self.parse_keywords(&[Keyword::IF, Keyword::EXISTS]);
29912995
let func_desc = self.parse_comma_separated(Parser::parse_drop_function_desc)?;
@@ -3019,8 +3023,10 @@ impl<'a> Parser<'a> {
30193023
Ok(DropFunctionDesc { name, args })
30203024
}
30213025

3026+
/// ```sql
30223027
/// DECLARE name [ BINARY ] [ ASENSITIVE | INSENSITIVE ] [ [ NO ] SCROLL ]
3023-
// CURSOR [ { WITH | WITHOUT } HOLD ] FOR query
3028+
/// CURSOR [ { WITH | WITHOUT } HOLD ] FOR query
3029+
/// ```
30243030
pub fn parse_declare(&mut self) -> Result<Statement, ParserError> {
30253031
let name = self.parse_identifier()?;
30263032

@@ -4822,7 +4828,7 @@ impl<'a> Parser<'a> {
48224828

48234829
/// Parse a "query body", which is an expression with roughly the
48244830
/// following grammar:
4825-
/// ```text
4831+
/// ```sql
48264832
/// query_body ::= restricted_select | '(' subquery ')' | set_operation
48274833
/// restricted_select ::= 'SELECT' [expr_list] [ from ] [ where ] [ groupby_having ]
48284834
/// subquery ::= query_body [ order_by_limit ]
@@ -6130,7 +6136,7 @@ impl<'a> Parser<'a> {
61306136
}
61316137

61326138
/// Parse a TOP clause, MSSQL equivalent of LIMIT,
6133-
/// that follows after SELECT [DISTINCT].
6139+
/// that follows after `SELECT [DISTINCT]`.
61346140
pub fn parse_top(&mut self) -> Result<Top, ParserError> {
61356141
let quantity = if self.consume_token(&Token::LParen) {
61366142
let quantity = self.parse_expr()?;
@@ -6449,8 +6455,11 @@ impl<'a> Parser<'a> {
64496455
})
64506456
}
64516457

6452-
/// https://www.postgresql.org/docs/current/sql-createsequence.html
6458+
/// ```sql
64536459
/// CREATE [ { TEMPORARY | TEMP } ] SEQUENCE [ IF NOT EXISTS ] <sequence_name>
6460+
/// ```
6461+
///
6462+
/// See [Postgres docs](https://www.postgresql.org/docs/current/sql-createsequence.html) for more details.
64546463
pub fn parse_create_sequence(&mut self, temporary: bool) -> Result<Statement, ParserError> {
64556464
//[ IF NOT EXISTS ]
64566465
let if_not_exists = self.parse_keywords(&[Keyword::IF, Keyword::NOT, Keyword::EXISTS]);

0 commit comments

Comments
 (0)