Update our macros to work in the 2018 style

diesel/src/associations/belongs_to.rs

@@ -46,7 +46,6 @@ pub trait BelongsTo<Parent> {
 /// # Example
 ///
 /// ```rust
-/// # #[macro_use] extern crate diesel;
 /// # include!("../doctest_setup.rs");
 /// # use schema::{posts, users};
 /// #

diesel/src/associations/mod.rs

@@ -5,7 +5,6 @@
 //! Unlike other ORMs, Diesel has no concept of `#[has_many`]
 //!
 //! ```rust
-//! # #[macro_use] extern crate diesel;
 //! # include!("../doctest_setup.rs");
 //! use schema::{posts, users};
 //!
@@ -54,7 +53,6 @@
 //! `unrestricted_attribute_tokens` is stable.
 //!
 //! ```rust
-//! # #[macro_use] extern crate diesel;
 //! # include!("../doctest_setup.rs");
 //! # use schema::{posts, users};
 //! # use std::borrow::Cow;
@@ -98,7 +96,6 @@
 //! [`belonging_to`]: ../query_dsl/trait.BelongingToDsl.html#tymethod.belonging_to
 //!
 //! ```rust
-//! # #[macro_use] extern crate diesel;
 //! # include!("../doctest_setup.rs");
 //! # use schema::users;
 //! # use schema::posts;
@@ -153,7 +150,6 @@
 //! [`belonging_to`]: ../query_dsl/trait.BelongingToDsl.html#tymethod.belonging_to
 //!
 //! ```rust
-//! # #[macro_use] extern crate diesel;
 //! # include!("../doctest_setup.rs");
 //! # use schema::{posts, users};
 //! #
@@ -208,7 +204,6 @@
 //! and it will be combined with its parent.
 //!
 //! ```rust
-//! # #[macro_use] extern crate diesel;
 //! # include!("../doctest_setup.rs");
 //! # use schema::{posts, users};
 //! #
@@ -270,7 +265,6 @@
 //! to make each line a bit more clear.
 //!
 //! ```rust
-//! # #[macro_use] extern crate diesel;
 //! # include!("../doctest_setup.rs");
 //! # use schema::{users, posts, comments};
 //! #
@@ -361,6 +355,9 @@ use crate::query_source::Table;
 
 pub use self::belongs_to::{BelongsTo, GroupedBy};
 
+#[doc(inline)]
+pub use diesel_derives::Associations;
+
 /// This trait indicates that a struct is associated with a single database table.
 ///
 /// This trait is implemented by structs which implement `Identifiable`,
@@ -389,25 +386,8 @@ impl<'a, T: HasTable> HasTable for &'a T {
 /// `update(YourStruct::table().find(&your_struct.primary_key())`).
 ///
 /// This trait is usually implemented on a reference to a struct,
-/// not the struct itself.
-///
-/// ### Deriving
+/// not on the struct itself. It can be [derived](derive.Identifiable.html).
 ///
-/// This trait can be automatically derived by adding `#[derive(Identifiable)]`
-/// to your struct.
-/// By default, the "id" field is assumed to be a single field called `id`.
-/// If it's not, you can put `#[primary_key(your_id)]` on your struct.
-/// If you have a composite primary key, the syntax is `#[primary_key(id1, id2)]`.
-///
-/// By default, `#[derive(Identifiable)]` will assume that your table
-/// name is the plural form of your struct name.
-/// Diesel uses very simple pluralization rules.
-/// It only adds an `s` to the end, and converts `CamelCase` to `snake_case`.
-/// If your table name does not follow this convention
-/// or the plural form isn't just an `s`,
-/// you can specify the table name with `#[table_name = "some_table_name"]`.
-/// Our rules for inferring table names is considered public API.
-/// It will never change without a major version bump.
 pub trait Identifiable: HasTable {
     /// The type of this struct's identifier.
     ///
@@ -428,3 +408,6 @@ pub trait Identifiable: HasTable {
     /// so that we have a lifetime to use for `Id`.
     fn id(self) -> Self::Id;
 }
+
+#[doc(inline)]
+pub use diesel_derives::Identifiable;

diesel/src/connection/mod.rs

@@ -48,7 +48,6 @@ pub trait Connection: SimpleConnection + Sized + Send {
     /// # Example
     ///
     /// ```rust
-    /// # #[macro_use] extern crate diesel;
     /// # include!("../doctest_setup.rs");
     /// use diesel::result::Error;
     ///
@@ -121,7 +120,6 @@ pub trait Connection: SimpleConnection + Sized + Send {
     /// # Example
     ///
     /// ```rust
-    /// # #[macro_use] extern crate diesel;
     /// # include!("../doctest_setup.rs");
     /// use diesel::result::Error;
     ///

diesel/src/deserialize.rs

@@ -19,28 +19,13 @@ pub type Result<T> = result::Result<T, Box<dyn Error + Send + Sync>>;
 /// trait is to convert from a tuple of Rust values that have been deserialized
 /// into your struct.
 ///
-/// # Deriving
-///
-/// This trait can be derived automatically using `#[derive(Queryable)]`. This
-/// trait can only be derived for structs, not enums.
-///
-/// When this trait is derived, it will assume that the order of fields on your
-/// struct match the order of the fields in the query. This means that field
-/// order is significant if you are using `#[derive(Queryable)]`. Field name has
-/// no effect.
-///
-/// To provide custom deserialization behavior for a field, you can use
-/// `#[diesel(deserialize_as = "Type")]`. If this attribute is present, Diesel
-/// will deserialize into that type, rather than the type on your struct and
-/// call `.into` to convert it. This can be used to add custom behavior for a
-/// single field, or use types that are otherwise unsupported by Diesel.
+/// This trait can be [derived](derive.Queryable.html)
 ///
 /// # Examples
 ///
 /// If we just want to map a query to our struct, we can use `derive`.
 ///
 /// ```rust
-/// # #[macro_use] extern crate diesel;
 /// # include!("doctest_setup.rs");
 /// #
 /// #[derive(Queryable, PartialEq, Debug)]
@@ -67,7 +52,6 @@ pub type Result<T> = result::Result<T, Box<dyn Error + Send + Sync>>;
 /// `deserialize_as` to use a different implementation.
 ///
 /// ```rust
-/// # #[macro_use] extern crate diesel;
 /// # include!("doctest_setup.rs");
 /// #
 /// # use schema::users;
@@ -118,7 +102,6 @@ pub type Result<T> = result::Result<T, Box<dyn Error + Send + Sync>>;
 /// Alternatively, we can implement the trait for our struct manually.
 ///
 /// ```rust
-/// # #[macro_use] extern crate diesel;
 /// # include!("doctest_setup.rs");
 /// #
 /// use schema::users;
@@ -171,43 +154,20 @@ where
     fn build(row: Self::Row) -> Self;
 }
 
+#[doc(inline)]
+pub use diesel_derives::Queryable;
+
 /// Deserializes the result of a query constructed with [`sql_query`].
 ///
-/// # Deriving
-///
-/// To derive this trait, Diesel needs to know the SQL type of each field. You
-/// can do this by either annotating your struct with `#[table_name =
-/// "some_table"]` (in which case the SQL type will be
-/// `diesel::dsl::SqlTypeOf<table_name::column_name>`), or by annotating each
-/// field with `#[sql_type = "SomeType"]`.
-///
-/// If you are using `#[table_name]`, the module for that table must be in
-/// scope. For example, to derive this for a struct called `User`, you will
-/// likely need a line such as `use schema::users;`
-///
-/// If the name of a field on your struct is different than the column in your
-/// `table!` declaration, or if you are deriving this trait on a tuple struct,
-/// you can annotate the field with `#[column_name = "some_column"]`. For tuple
-/// structs, all fields must have this annotation.
-///
-/// If a field is another struct which implements `QueryableByName`, instead of
-/// a column, you can annotate that struct with `#[diesel(embed)]`
-///
-/// To provide custom deserialization behavior for a field, you can use
-/// `#[diesel(deserialize_as = "Type")]`. If this attribute is present, Diesel
-/// will deserialize into that type, rather than the type on your struct and
-/// call `.into` to convert it. This can be used to add custom behavior for a
-/// single field, or use types that are otherwise unsupported by Diesel.
+/// This trait can be [derived](derive.QueryableByName.html)
 ///
 /// [`sql_query`]: ../fn.sql_query.html
 ///
 /// # Examples
 ///
-///
 /// If we just want to map a query to our struct, we can use `derive`.
 ///
 /// ```rust
-/// # #[macro_use] extern crate diesel;
 /// # include!("doctest_setup.rs");
 /// # use schema::users;
 /// # use diesel::sql_query;
@@ -237,7 +197,6 @@ where
 /// `deserialize_as` to use a different implementation.
 ///
 /// ```rust
-/// # #[macro_use] extern crate diesel;
 /// # include!("doctest_setup.rs");
 /// # use diesel::sql_query;
 /// # use schema::users;
@@ -293,6 +252,9 @@ where
     fn build<R: NamedRow<DB>>(row: &R) -> Result<Self>;
 }
 
+#[doc(inline)]
+pub use diesel_derives::QueryableByName;
+
 /// Deserialize a single field of a given SQL type.
 ///
 /// When possible, implementations of this trait should prefer to use an
@@ -361,12 +323,7 @@ pub trait FromSql<A, DB: Backend>: Sized {
 /// for all types which implement `FromSql`. However, as of Diesel 1.0, such an
 /// impl would conflict with our impl for tuples.
 ///
-/// ## Deriving
-///
-/// This trait can be automatically derived by Diesel
-/// for any type which implements `FromSql`.
-/// There are no options or special considerations needed for this derive.
-/// Note that `#[derive(FromSqlRow)]` will also generate a `Queryable` implementation.
+/// This trait can be [derived](derive.FromSqlRow.html)
 pub trait FromSqlRow<A, DB: Backend>: Sized {
     /// The number of fields that this type will consume. Must be equal to
     /// the number of times you would call `row.take()` in `build_from_row`
@@ -376,6 +333,9 @@ pub trait FromSqlRow<A, DB: Backend>: Sized {
     fn build_from_row<T: Row<DB>>(row: &mut T) -> Result<Self>;
 }
 
+#[doc(inline)]
+pub use diesel_derives::FromSqlRow;
+
 // Reasons we can't write this:
 //
 // impl<T, ST, DB> FromSqlRow<ST, DB> for T

diesel/src/doctest_setup.rs

@@ -197,6 +197,8 @@ fn database_url_from_env(backend_specific_env_var: &str) -> String {
 
 
 mod schema {
+    use diesel::prelude::*;
+
     table! {
         animals {
             id -> Integer,

diesel/src/expression/count.rs

@@ -1,3 +1,4 @@
+use super::functions::sql_function;
 use super::Expression;
 use crate::backend::Backend;
 use crate::query_builder::*;
@@ -14,7 +15,6 @@ sql_function! {
     /// # Examples
     ///
     /// ```rust
-    /// # #[macro_use] extern crate diesel;
     /// # include!("../doctest_setup.rs");
     /// # use diesel::dsl::*;
     /// #
@@ -41,7 +41,6 @@ sql_function! {
 /// # Examples
 ///
 /// ```rust
-/// # #[macro_use] extern crate diesel;
 /// # include!("../doctest_setup.rs");
 /// # use diesel::dsl::*;
 /// #

diesel/src/expression/exists.rs

@@ -13,7 +13,6 @@ use crate::sql_types::Bool;
 /// # Example
 ///
 /// ```rust
-/// # #[macro_use] extern crate diesel;
 /// # include!("../doctest_setup.rs");
 /// #
 /// # fn main() {

diesel/src/expression/functions/aggregate_folding.rs

@@ -1,3 +1,4 @@
+use crate::expression::functions::sql_function;
 use crate::sql_types::Foldable;
 
 sql_function! {
@@ -7,7 +8,6 @@ sql_function! {
     /// # Examples
     ///
     /// ```rust
-    /// # #[macro_use] extern crate diesel;
     /// # include!("../../doctest_setup.rs");
     /// # use diesel::dsl::*;
     /// #
@@ -28,7 +28,6 @@ sql_function! {
     /// # Examples
     ///
     /// ```rust
-    /// # #[macro_use] extern crate diesel;
     /// # include!("../../doctest_setup.rs");
     /// # use diesel::dsl::*;
     /// # #[cfg(feature = "bigdecimal")]

diesel/src/expression/functions/aggregate_ordering.rs

@@ -1,3 +1,4 @@
+use crate::expression::functions::sql_function;
 use crate::sql_types::{IntoNullable, SqlOrd};
 
 sql_function! {
@@ -7,7 +8,6 @@ sql_function! {
     /// # Examples
     ///
     /// ```rust
-    /// # #[macro_use] extern crate diesel;
     /// # include!("../../doctest_setup.rs");
     /// # use diesel::dsl::*;
     /// #
@@ -27,7 +27,6 @@ sql_function! {
     /// # Examples
     ///
     /// ```rust
-    /// # #[macro_use] extern crate diesel;
     /// # include!("../../doctest_setup.rs");
     /// # use diesel::dsl::*;
     /// #

diesel/src/expression/functions/date_and_time.rs

@@ -1,5 +1,6 @@
 use crate::backend::Backend;
 use crate::expression::coerce::Coerce;
+use crate::expression::functions::sql_function;
 use crate::expression::{AsExpression, Expression};
 use crate::query_builder::*;
 use crate::result::QueryResult;
@@ -33,7 +34,6 @@ sql_function! {
     /// # Examples
 
     /// ```ignore
-    /// # #[macro_use] extern crate diesel;
     /// # extern crate chrono;
     /// # include!("../../doctest_setup.rs");
     /// # use diesel::dsl::*;