Skip to content

Commit bc687a3

Browse files
sgrifsgrif
authored
Merge pull request diesel-rs#1375 from diesel-rs/sg-doc-query-dsl
Document all items in `query_dsl`.
2 parents 3f76e34 + 1d7c48c commit bc687a3

9 files changed

Lines changed: 100 additions & 80 deletions

File tree

‎diesel/src/lib.rs‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ pub mod pg;
7373
#[deny(missing_docs)]
7474
pub mod sqlite;
7575

76+
#[deny(missing_docs)]
7677
pub mod query_dsl;
7778
pub mod query_source;
7879
pub mod result;
@@ -169,8 +170,9 @@ pub mod prelude {
169170
pub use expression_methods::*;
170171
#[doc(inline)]
171172
pub use insertable::Insertable;
172-
pub use query_dsl::{BelongingToDsl, GroupByDsl, JoinOnDsl, QueryDsl, RunQueryDsl,
173-
SaveChangesDsl};
173+
#[doc(hidden)]
174+
pub use query_dsl::GroupByDsl;
175+
pub use query_dsl::{BelongingToDsl, JoinOnDsl, QueryDsl, RunQueryDsl, SaveChangesDsl};
174176

175177
pub use query_source::{Column, JoinTo, QuerySource, Queryable, Table};
176178
pub use result::{ConnectionError, ConnectionResult, OptionalExtension, QueryResult};

‎diesel/src/query_dsl/belonging_to_dsl.rs‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
#![deny(missing_docs)]
2-
/// Find record(s) belonging to the given parent(s).
1+
/// Constructs a query that finds record(s) based on directional association with other record(s).
32
///
43
/// # Example
54
///

‎diesel/src/query_dsl/distinct_dsl.rs‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
#![deny(missing_docs)]
21
use query_source::Table;
32
#[cfg(feature = "postgres")]
43
use expression::SelectableExpression;

‎diesel/src/query_dsl/group_by_dsl.rs‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,22 @@ use expression::Expression;
22
use query_builder::{AsQuery, Query};
33
use query_source::Table;
44

5+
/// This trait is not yet part of Diesel's public API. It may change in the
6+
/// future without a major version bump.
7+
///
8+
/// This trait exists as a stop-gap for users who need to use `GROUP BY` in
9+
/// their queries, so that they are not forced to drop entirely to raw SQL. The
10+
/// arguments to `group_by` are not checked, nor is the select statement
11+
/// forced to be valid.
12+
///
13+
/// Since Diesel otherwise assumes that you have no `GROUP BY` clause (which
14+
/// would mean that mixing an aggregate and non aggregate expression in the same
15+
/// query is an error), you may need to use `sql` for your select clause.
516
pub trait GroupByDsl<Expr: Expression> {
17+
/// The type returned by `.group_by`
618
type Output: Query;
719

20+
/// See the trait documentation.
821
fn group_by(self, expr: Expr) -> Self::Output;
922
}
1023

‎diesel/src/query_dsl/join_dsl.rs‎

Lines changed: 28 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -44,34 +44,35 @@ where
4444
}
4545
}
4646

47+
/// Specify the `ON` clause for a join statement. This will override
48+
/// any implicit `ON` clause that would come from [`joinable!`]
49+
///
50+
/// [`joinable!`]: ../macro.joinable.html
51+
///
52+
/// # Example
53+
///
54+
/// ```rust
55+
/// # #[macro_use] extern crate diesel;
56+
/// # include!("../doctest_setup.rs");
57+
/// # use schema::{users, posts};
58+
/// #
59+
/// # fn main() {
60+
/// # let connection = establish_connection();
61+
/// let data = users::table
62+
/// .left_join(posts::table.on(
63+
/// users::id.eq(posts::user_id).and(
64+
/// posts::title.eq("My first post"))
65+
/// ))
66+
/// .select((users::name, posts::title.nullable()))
67+
/// .load(&connection);
68+
/// let expected = vec![
69+
/// ("Sean".to_string(), Some("My first post".to_string())),
70+
/// ("Tess".to_string(), None),
71+
/// ];
72+
/// assert_eq!(Ok(expected), data);
73+
/// # }
4774
pub trait JoinOnDsl: Sized {
48-
/// Specify the `ON` clause for a join statement. This will override
49-
/// any implicit `ON` clause that would come from [`joinable!`]
50-
///
51-
/// [`joinable!`]: ../macro.joinable.html
52-
///
53-
/// # Example
54-
///
55-
/// ```rust
56-
/// # #[macro_use] extern crate diesel;
57-
/// # include!("../doctest_setup.rs");
58-
/// # use schema::{users, posts};
59-
/// #
60-
/// # fn main() {
61-
/// # let connection = establish_connection();
62-
/// let data = users::table
63-
/// .left_join(posts::table.on(
64-
/// users::id.eq(posts::user_id).and(
65-
/// posts::title.eq("My first post"))
66-
/// ))
67-
/// .select((users::name, posts::title.nullable()))
68-
/// .load(&connection);
69-
/// let expected = vec![
70-
/// ("Sean".to_string(), Some("My first post".to_string())),
71-
/// ("Tess".to_string(), None),
72-
/// ];
73-
/// assert_eq!(Ok(expected), data);
74-
/// # }
75+
/// See the trait documentation.
7576
fn on<On>(self, on: On) -> OnClauseWrapper<Self, On> {
7677
OnClauseWrapper::new(self, on)
7778
}

‎diesel/src/query_dsl/mod.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ pub mod methods {
6666
pub use super::select_dsl::SelectDsl;
6767
}
6868

69+
/// Methods used to construct select statements.
6970
pub trait QueryDsl: Sized {
7071
/// Adds the `DISTINCT` keyword to a query.
7172
///
@@ -756,6 +757,7 @@ pub trait QueryDsl: Sized {
756757

757758
impl<T: Table> QueryDsl for T {}
758759

760+
/// Methods used to execute queries.
759761
pub trait RunQueryDsl<Conn>: Sized {
760762
/// Executes the given command, returning the number of rows affected.
761763
///

‎diesel/src/query_dsl/offset_dsl.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ use query_source::Table;
88
///
99
/// [`QueryDsl`]: ../trait.QueryDsl.html
1010
pub trait OffsetDsl {
11+
/// The type returned by `.offset`.
1112
type Output;
1213

1314
/// See the trait documentation

‎diesel/src/query_dsl/order_dsl.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,10 @@ use query_source::Table;
99
///
1010
/// [`QueryDsl`]: ../trait.QueryDsl.html
1111
pub trait OrderDsl<Expr: Expression> {
12+
/// The type returned by `.order`.
1213
type Output;
1314

15+
/// See the trait documentation.
1416
fn order(self, expr: Expr) -> Self::Output;
1517
}
1618

‎diesel/src/query_dsl/save_changes_dsl.rs‎

Lines changed: 49 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -66,55 +66,56 @@ where
6666
}
6767
}
6868

69+
/// Sugar for types which implement both `AsChangeset` and `Identifiable`
70+
///
71+
/// On backends which support the `RETURNING` keyword,
72+
/// `foo.save_changes(&conn)` is equivalent to
73+
/// `update(&foo).set(&foo).get_result(&conn)`.
74+
/// On other backends, two queries will be executed.
75+
///
76+
/// # Example
77+
///
78+
/// ```rust
79+
/// # #[macro_use] extern crate diesel;
80+
/// # include!("../doctest_setup.rs");
81+
/// # use schema::animals;
82+
/// #
83+
/// #[derive(Queryable, Debug, PartialEq)]
84+
/// struct Animal {
85+
/// id: i32,
86+
/// species: String,
87+
/// legs: i32,
88+
/// name: Option<String>,
89+
/// }
90+
///
91+
/// #[derive(AsChangeset, Identifiable)]
92+
/// #[table_name = "animals"]
93+
/// struct AnimalForm<'a> {
94+
/// id: i32,
95+
/// name: &'a str,
96+
/// }
97+
///
98+
/// # fn main() {
99+
/// # run_test();
100+
/// # }
101+
/// #
102+
/// # fn run_test() -> QueryResult<()> {
103+
/// # use animals::dsl::*;
104+
/// # let connection = establish_connection();
105+
/// let form = AnimalForm { id: 2, name: "Super scary" };
106+
/// let changed_animal = form.save_changes(&connection)?;
107+
/// let expected_animal = Animal {
108+
/// id: 2,
109+
/// species: String::from("spider"),
110+
/// legs: 8,
111+
/// name: Some(String::from("Super scary")),
112+
/// };
113+
/// assert_eq!(expected_animal, changed_animal);
114+
/// # Ok(())
115+
/// # }
116+
/// ```
69117
pub trait SaveChangesDsl<Conn> {
70-
/// Sugar for types which implement both `AsChangeset` and `Identifiable`
71-
///
72-
/// On backends which support the `RETURNING` keyword,
73-
/// `foo.save_changes(&conn)` is equivalent to
74-
/// `update(&foo).set(&foo).get_result(&conn)`.
75-
/// On other backends, two queries will be executed.
76-
///
77-
/// # Example
78-
///
79-
/// ```rust
80-
/// # #[macro_use] extern crate diesel;
81-
/// # include!("../doctest_setup.rs");
82-
/// # use schema::animals;
83-
/// #
84-
/// #[derive(Queryable, Debug, PartialEq)]
85-
/// struct Animal {
86-
/// id: i32,
87-
/// species: String,
88-
/// legs: i32,
89-
/// name: Option<String>,
90-
/// }
91-
///
92-
/// #[derive(AsChangeset, Identifiable)]
93-
/// #[table_name = "animals"]
94-
/// struct AnimalForm<'a> {
95-
/// id: i32,
96-
/// name: &'a str,
97-
/// }
98-
///
99-
/// # fn main() {
100-
/// # run_test();
101-
/// # }
102-
/// #
103-
/// # fn run_test() -> QueryResult<()> {
104-
/// # use animals::dsl::*;
105-
/// # let connection = establish_connection();
106-
/// let form = AnimalForm { id: 2, name: "Super scary" };
107-
/// let changed_animal = form.save_changes(&connection)?;
108-
/// let expected_animal = Animal {
109-
/// id: 2,
110-
/// species: String::from("spider"),
111-
/// legs: 8,
112-
/// name: Some(String::from("Super scary")),
113-
/// };
114-
/// assert_eq!(expected_animal, changed_animal);
115-
/// # Ok(())
116-
/// # }
117-
/// ```
118+
/// See the trait documentation.
118119
fn save_changes<T>(self, connection: &Conn) -> QueryResult<T>
119120
where
120121
Self: InternalSaveChangesDsl<Conn, T>,

0 commit comments

Comments
 (0)