Repository: diesel-rs/diesel
File: diesel/src/query_dsl/mod.rs (Rust)

Code before:
    ///
    /// ```sql
    /// SELECT * FROM users
    ///     INNER JOIN (
    ///         posts
    ///         INNER JOIN comments ON comments.post_id = posts.id
    ///     ) ON posts.user_id = users.id
    ///
    /// ```
    ///
    /// While the second query would deserialize into `(User, Post, Comment)` and
    /// generate the following SQL:
    ///
    /// ```sql
    /// SELECT * FROM users
    ///     INNER JOIN posts ON posts.user_id = users.id
    ///     INNER JOIN comments ON comments.user_id = users.id
    /// ```
    ///
    /// The exact generated SQL may change in future diesel version as long as the
    /// generated query continue to produce same results. The currently generated
    /// SQL is refered as ["explicit join"](https://www.postgresql.org/docs/current/explicit-joins.html)
    /// by the PostgreSQL documentation and may have implications on the choosen query plan
    /// for large numbers of joins in the same query. Checkout the documentation of the
    /// [`join_collapse_limit` paramater](https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-JOIN-COLLAPSE-LIMIT)
    /// to control this behaviour.
    ///
    ///
    /// [associations]: crate::associations
    /// [`allow_tables_to_appear_in_same_query!`]: crate::allow_tables_to_appear_in_same_query!
    ///
    /// # Examples
    ///
    /// ### With implicit `ON` clause
    ///
    /// ```rust
    /// # include!("../doctest_setup.rs");
    /// # use schema::{users, posts};
    /// # /*
    /// joinable!(posts -> users (user_id));
    /// allow_tables_to_appear_in_same_query!(users, posts);
    /// # */
    ///
    /// # fn main() {
    /// #     use self::users::dsl::{users, name};
    /// #     use self::posts::dsl::{posts, user_id, title};
    /// #     let connection = &mut establish_connection();
    /// let data = users.inner_join(posts)
    ///     .select((name, title))
    ///     .load(connection);
    ///

Review comment (suggestion):
```suggestion
    /// The exact generated SQL may change in future diesel version as long as the
    /// generated query continues to produce same results. The currently generated
    /// SQL is referred as ["explicit join"](https://www.postgresql.org/docs/current/explicit-joins.html)
    /// by the PostgreSQL documentation and may have implications on the chosen query plan
    /// for large numbers of joins in the same query. Checkout the documentation of the
    /// [`join_collapse_limit` paramater](https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-JOIN-COLLAPSE-LIMIT)
    /// to control this behaviour.
```

Code after:
    ///
    /// ```sql
    /// SELECT * FROM users
    ///     INNER JOIN (
    ///         posts
    ///         INNER JOIN comments ON comments.post_id = posts.id
    ///     ) ON posts.user_id = users.id
    ///
    /// ```
    ///
    /// While the second query would deserialize into `(User, Post, Comment)` and
    /// generate the following SQL:
    ///
    /// ```sql
    /// SELECT * FROM users
    ///     INNER JOIN posts ON posts.user_id = users.id
    ///     INNER JOIN comments ON comments.user_id = users.id
    /// ```
    ///
    /// The exact generated SQL may change in future diesel version as long as the
    /// generated query continues to produce same results. The currently generated
    /// SQL is referred as ["explicit join"](https://www.postgresql.org/docs/current/explicit-joins.html)
    /// by the PostgreSQL documentation and may have implications on the chosen query plan
    /// for large numbers of joins in the same query. Checkout the documentation of the
    /// [`join_collapse_limit` paramater](https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-JOIN-COLLAPSE-LIMIT)
    /// to control this behaviour.
    ///
    /// [associations]: crate::associations
    /// [`allow_tables_to_appear_in_same_query!`]: crate::allow_tables_to_appear_in_same_query!
    ///
    /// # Examples
    ///
    /// ### With implicit `ON` clause
    ///
    /// ```rust
    /// # include!("../doctest_setup.rs");
    /// # use schema::{users, posts};
    /// # /*
    /// joinable!(posts -> users (user_id));
    /// allow_tables_to_appear_in_same_query!(users, posts);
    /// # */
    ///
    /// # fn main() {
    /// #     use self::users::dsl::{users, name};
    /// #     use self::posts::dsl::{posts, user_id, title};
    /// #     let connection = &mut establish_connection();
    /// let data = users.inner_join(posts)
    ///     .select((name, title))
    ///     .load(connection);
    ///
    /// let expected_data = vec![