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

Code before:
    ///
    /// If there was already a select clause present, it will be overridden.
    /// For example, `foo.select(bar).select(baz)` will produce the same
    /// query as `foo.select(baz)`.
    ///
    /// By default, the select clause will be roughly equivalent to `SELECT *`
    /// (however, Diesel will list all columns to ensure that they are in the
    /// order we expect).
    ///
    /// `select` has slightly stricter bounds on its arguments than other
    /// methods. In particular, when used with a left outer join, `.nullable`
    /// must be called on columns that come from the right side of a join. It
    /// can be called on the column itself, or on an expression containing that
    /// column. `title.nullable()`, `lower(title).nullable()`, and `(id,
    /// title).nullable()` would all be valid.
    ///
    /// Note that in order to use this method with a method like [`.inner_join`] or [`.filter`],
    /// you will need to use it before calling [`.select`] (See examples below).
    /// This is because you can only access columns from tables
    /// that appear in your query before that function call.
    ///
    /// [`.inner_join`]: QueryDsl::inner_join()
    /// [`.filter`]: QueryDsl::filter()
    /// [`.select`]: QueryDsl::select()
    ///
    /// # Examples
    ///
    /// ```rust
    /// # include!("../doctest_setup.rs");
    /// # use schema::users;
    /// #
    /// # fn main() {
    /// #     run_test().unwrap();
    /// # }
    /// #
    /// # fn run_test() -> QueryResult<()> {
    /// #     use self::users::dsl::*;
    /// #     let connection = &mut establish_connection();
    /// // By default, all columns will be selected
    /// let all_users = users.load::<(i32, String)>(connection)?;
    /// assert_eq!(vec![(1, String::from("Sean")), (2, String::from("Tess"))], all_users);
    ///
    /// let all_names = users.select(name).load::<String>(connection)?;
    /// assert_eq!(vec!["Sean", "Tess"], all_names);
    /// #     Ok(())
    /// # }
    /// ```
    ///
    /// ### When used with a left join
    ///
    /// ```rust

Review comment (suggestion):
This should only mention `inner_join`/`left_join`, but **not** `filter. The ordering of `.select` and `filter` calls does not matter.

I also would like to suggest a slightly different wording here:
```suggestion
    /// In order to use this method with columns from different tables 
    /// a method like [`.inner_join`] or [`.left_join`] needs to be called before 
    /// calling [`.select`] (See examples below).
    /// This is because you can only access columns from tables
    /// that appear in your query before that function call.
    ///
    /// [`.inner_join`]: QueryDsl::inner_join()
    /// [`.left_join`]: QueryDsl::left_join()
    /// [`.select`]: QueryDsl::select()
    ///
```

Code after:
    ///
    /// If there was already a select clause present, it will be overridden.
    /// For example, `foo.select(bar).select(baz)` will produce the same
    /// query as `foo.select(baz)`.
    ///
    /// By default, the select clause will be roughly equivalent to `SELECT *`
    /// (however, Diesel will list all columns to ensure that they are in the
    /// order we expect).
    ///
    /// `select` has slightly stricter bounds on its arguments than other
    /// methods. In particular, when used with a left outer join, `.nullable`
    /// must be called on columns that come from the right side of a join. It
    /// can be called on the column itself, or on an expression containing that
    /// column. `title.nullable()`, `lower(title).nullable()`, and `(id,
    /// title).nullable()` would all be valid.
    ///
    /// In order to use this method with columns from different tables
    /// a method like [`.inner_join`] or [`.left_join`] needs to be called before
    /// calling [`.select`] (See examples below).
    /// This is because you can only access columns from tables
    /// that appear in your query before that function call.
    ///
    /// [`.inner_join`]: QueryDsl::inner_join()
    /// [`.left_join`]: QueryDsl::left_join()
    /// [`.select`]: QueryDsl::select()
    ///
    /// # Examples
    ///
    /// ```rust
    /// # include!("../doctest_setup.rs");
    /// # use schema::users;
    /// #
    /// # fn main() {
    /// #     run_test().unwrap();
    /// # }
    /// #
    /// # fn run_test() -> QueryResult<()> {
    /// #     use self::users::dsl::*;
    /// #     let connection = &mut establish_connection();
    /// // By default, all columns will be selected
    /// let all_users = users.load::<(i32, String)>(connection)?;
    /// assert_eq!(vec![(1, String::from("Sean")), (2, String::from("Tess"))], all_users);
    ///
    /// let all_names = users.select(name).load::<String>(connection)?;
    /// assert_eq!(vec!["Sean", "Tess"], all_names);
    /// #     Ok(())
    /// # }
    /// ```
    ///
    /// ### When used with a left join
    ///