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

Code before:
//!
//! Diesel maps "Rust types" (e.g. `i32`) to and from "SQL types"
//! (e.g. [`diesel::sql_types::Integer`]).
//! You can find all the types supported by Diesel in [the `sql_types` module](sql_types).
//! These types are only used to represent a SQL type.
//! You should never put them on your `Queryable` structs.
//!
//! To find all the Rust types which can be used with a given SQL type,
//! see the documentation for that SQL type.
//!
//! To find all the SQL types which can be used with a Rust type,
//! go to the docs for either [`ToSql`] or [`FromSql`],
//! go to the "Implementors" section,
//! and find the Rust type you want to use.
//!
//! [`Queryable`]: deserialize::Queryable
//! [`diesel::sql_types::Integer`]: sql_types::Integer
//! [`ToSql`]: serialize::ToSql
//! [`FromSql`]: deserialize::FromSql
//!
//! ## How to read diesels compile time error messages
//!
//! Diesel is known for generating large complicated looking errors. Usually
//! most of these error messages can be break down easily. The following
//! section tries to give an overview of common error messages and how to read them.
//! As a general note it's always usefull to read the complete error message as emitted
//! by rustc, including the `required because of …` part of the message.
//! You IDE might hide important parts!
//!
//! If you use a nightly compiler you might want to enable the `nightly-error-messages`
//! feature flag to automatically improve some error messages.
//!
//! The following error messages are common:
//!
//! * `the trait bound (diesel::sql_types::Integer, …, diesel::sql_types::Text): load_dsl::private::CompatibleType<YourModel, Pg> is not satisfied`
//!    while trying to execute a query:
//!    This error indicates a mismatch between what your query returns and what your model struct
//!    expects the query to return. The fields need to match in terms of field order, field type
//!    and field count. If your are sure that everything must match double check the enabled diesel
//!    features (for support for types from other crates) and double check (via `cargo tree`)
//!    that there is only one version of such a shared crate in your dependency tree.
//!    Consider using [`#[derive(Selectable)]`](derive@crate::prelude::Selectable) +
//!    `#[diesel(check_for_backend(diesel::pg::Pg))]`
//!    to improve the generated error message.
//! * `the trait bound i32: diesel::Expression is not satisfied` in the context of `Insertable`
//!    model structs:
//!    This error indicates a type mismatch between the field you are trying to insert into the database
//!    and the actual database type. These error messages contain a line
//!    like ` = note: required for i32 to implement AsExpression<diesel::sql_types::Text>`
//!    that show both the provided rust side type (`i32` in that case) and the expected
//!    database side type (`Text` in that case).

Review comment (suggestion):
```suggestion
//! As a general note it's always useful to read the complete error message as emitted
```

Code after:
//!
//! Diesel maps "Rust types" (e.g. `i32`) to and from "SQL types"
//! (e.g. [`diesel::sql_types::Integer`]).
//! You can find all the types supported by Diesel in [the `sql_types` module](sql_types).
//! These types are only used to represent a SQL type.
//! You should never put them on your `Queryable` structs.
//!
//! To find all the Rust types which can be used with a given SQL type,
//! see the documentation for that SQL type.
//!
//! To find all the SQL types which can be used with a Rust type,
//! go to the docs for either [`ToSql`] or [`FromSql`],
//! go to the "Implementors" section,
//! and find the Rust type you want to use.
//!
//! [`Queryable`]: deserialize::Queryable
//! [`diesel::sql_types::Integer`]: sql_types::Integer
//! [`ToSql`]: serialize::ToSql
//! [`FromSql`]: deserialize::FromSql
//!
//! ## How to read diesels compile time error messages
//!
//! Diesel is known for generating large complicated looking errors. Usually
//! most of these error messages can be broken down easily. The following
//! section tries to give an overview of common error messages and how to read them.
//! As a general note it's always useful to read the complete error message as emitted
//! by rustc, including the `required because of …` part of the message.
//! Your IDE might hide important parts!
//!
//! If you use a nightly compiler you might want to enable the `nightly-error-messages`
//! feature flag to automatically improve some error messages.
//!
//! The following error messages are common:
//!
//! * `the trait bound (diesel::sql_types::Integer, …, diesel::sql_types::Text): load_dsl::private::CompatibleType<YourModel, Pg> is not satisfied`
//!    while trying to execute a query:
//!    This error indicates a mismatch between what your query returns and what your model struct
//!    expects the query to return. The fields need to match in terms of field order, field type
//!    and field count. If you are sure that everything matches, double check the enabled diesel
//!    features (for support for types from other crates) and double check (via `cargo tree`)
//!    that there is only one version of such a shared crate in your dependency tree.
//!    Consider using [`#[derive(Selectable)]`](derive@crate::prelude::Selectable) +
//!    `#[diesel(check_for_backend(diesel::pg::Pg))]`
//!    to improve the generated error message.
//! * `the trait bound i32: diesel::Expression is not satisfied` in the context of `Insertable`
//!    model structs:
//!    This error indicates a type mismatch between the field you are trying to insert into the database
//!    and the actual database type. These error messages contain a line
//!    like ` = note: required for i32 to implement AsExpression<diesel::sql_types::Text>`
//!    that show both the provided rust side type (`i32` in that case) and the expected
//!    database side type (`Text` in that case).