Documentation pass for diesel_codegen

This adds proper documentation for everything provided by `codegen`.
With the old crate, it was just a giant blob of text in the README. Now
the procedural macros all appear in the proper documentation, so we can
document everything inline.

[ci skip]

diesel/src/associations/mod.rs

@@ -122,6 +122,19 @@ use query_source::Table;
 
 pub use self::belongs_to::{BelongsTo, GroupedBy};
 
+/// Represents a struct which can be identified on a single table in the
+/// database. This must be implemented to use associations, and some features of
+/// updating.
+///
+/// ### Deriving
+///
+/// This trait can be automatically derived using `diesel_codegen` by adding
+/// `#[derive(Identifiable)]` to your struct. The primary key will be assumed to be a field and
+/// column called `id`. By default the table will be assumed to be the plural form of the struct
+/// name (using *very* dumb pluralization -- it just adds an `s` at the end). If your table name
+/// differs from that convention, or requires complex pluralization, it can be specified using
+/// `#[table_name = "some_table_name"]`. The inferred table name is considered public API and will
+/// never change without a major version bump.
 pub trait Identifiable {
     type Id: Hash + Eq;
     type Table: Table + for<'a> FindDsl<&'a Self::Id>;

diesel/src/macros/macros_from_codegen.rs

@@ -1,8 +1,14 @@
 #[macro_export]
+/// Queries the database for the names of all tables, and calls
+/// [`infer_table_from_schema!`](macro.infer_table_from_schema!.html) for each
+/// one.
+///
+/// Attempting to use the `env!` or `dotenv!` macros here will not work due to limitations of
+/// the Macros 1.1 system, but you can pass a string in the form `"env:SOME_ENV_VAR"` or
+/// `"dotenv:SOME_ENV_VAR"` to achieve the same effect.
+///
 /// This macro can only be used in combination with the `diesel_codegen` or
 /// `diesel_codegen_syntex` crates. It will not work on its own.
-///
-/// FIXME: Oh look we have a place to actually document this now.
 macro_rules! infer_schema {
     ($database_url: expr) => {
         #[derive(InferSchema)]
@@ -12,10 +18,20 @@ macro_rules! infer_schema {
 }
 
 #[macro_export]
+/// Establishes a database connection at compile time, loads the schema information about a table's
+/// columns, and invokes [`table!`](macro.table!.html) for you automatically.
+///
+/// Attempting to use the `env!` or `dotenv!` macros here will not work due to limitations of the
+/// Macros 1.1 system, but you can pass a string in the form `"env:SOME_ENV_VAR"` or
+/// `"dotenv:SOME_ENV_VAR"` to achieve the same effect.
+///
+/// At this time, the schema inference macros do not support types from third party crates, and
+/// having any columns with a type not supported by the diesel core crate will result in a compiler
+/// error (please [open an issue](https://github.com/diesel-rs/diesel/issues/new) if this happens
+/// unexpectedly for a type listed in our docs.)
+///
 /// This macro can only be used in combination with the `diesel_codegen` or
 /// `diesel_codegen_syntex` crates. It will not work on its own.
-///
-/// FIXME: Oh look we have a place to actually document this now.
 macro_rules! infer_table_from_schema {
     ($database_url: expr, $table_name: expr) => {
         #[derive(InferTableFromSchema)]
@@ -25,10 +41,19 @@ macro_rules! infer_table_from_schema {
 }
 
 #[macro_export]
+/// This macro will read your migrations at compile time, and embed a module you can use to execute
+/// them at runtime without the migration files being present on the file system. This is useful if
+/// you would like to use Diesel's migration infrastructure, but want to ship a single executable
+/// file (such as for embedded applications). It can also be used to apply migrations to an in
+/// memory database (Diesel does this for its own test suite).
+///
+/// You can optionally pass the path to the migrations directory to this macro. When left
+/// unspecified, Diesel Codegen will search for the migrations directory in the same way that
+/// Diesel CLI does. If specified, the path should be relative to the directory where `Cargo.toml`
+/// resides.
+///
 /// This macro can only be used in combination with the `diesel_codegen` or
 /// `diesel_codegen_syntex` crates. It will not work on its own.
-///
-/// FIXME: Oh look we have a place to actually document this now.
 macro_rules! embed_migrations {
     () => {
         #[derive(EmbedMigrations)]

diesel/src/persistable.rs

@@ -7,9 +7,16 @@ use query_builder::{QueryBuilder, BuildQueryResult};
 use query_source::{Table, Column};
 
 /// Represents that a structure can be used to to insert a new row into the
-/// database.  Implementations can be automatically generated by
-/// `#[derive(Insertable)]` This is automatically implemented for `&[T]` and
-/// `&Vec<T>` for inserting more than one record.
+/// database. This is automatically implemented for `&[T]` and `&Vec<T>` for
+/// inserting more than one record.
+///
+/// ### Deriving
+///
+/// This trait can be automatically derived using `diesel_codegen` by adding
+/// `#[derive(Insertable)]` to your struct. Structs which derive this trait must
+/// also be annotated with `#[table_name = "some_table_name"]`. If the field
+/// name of your struct differs from the name of the column, you can annotate
+/// the field with `#[column_name = "some_column_name"]`.
 pub trait Insertable<T: Table, DB: Backend> {
     type Values: InsertValues<DB>;
 

diesel/src/query_builder/update_statement/changeset.rs

@@ -4,13 +4,20 @@ use query_source::QuerySource;
 use result::QueryResult;
 
 /// Types which can be passed to
-/// [`update.set`](struct.IncompleteUpdateStatement.html#method.set). This can
-/// be automatically generated for structs by `#[derive(AsChangeset)]`.
+/// [`update.set`](struct.IncompleteUpdateStatement.html#method.set).
 ///
-/// Structs which derive this trait must be annotated with `#[table_name = "something"]`. By
-/// default, any option fields on the struct are skipped if their value is `None`. If you would
-/// like to assign `NULL` to the field instead, you can annotate your struct with
-/// `#[changeset_options(treat_none_as_null = "true")]`
+/// ### Deriving
+///
+/// This trait can be automatically derived using `diesel_codegen` by adding
+/// `#[derive(AsChangeset)]` to your struct.  Structs which derive this trait
+/// must be annotated with `#[table_name = "something"]`. If the field name of
+/// your struct differs from the name of the column, you can annotate the field
+/// with `#[column_name = "some_column_name"]`.
+///
+/// By default, any `Option` fields on the struct are skipped if their value is
+/// `None`. If you would like to assign `NULL` to the field instead, you can
+/// annotate your struct with `#[changeset_options(treat_none_as_null =
+/// "true")]`.
 pub trait AsChangeset {
     type Target: QuerySource;
     type Changeset;

diesel/src/query_source/mod.rs

@@ -16,9 +16,8 @@ use types::{FromSqlRow, HasSqlType};
 pub use self::joins::JoinTo;
 
 /// Trait indicating that a record can be queried from the database. This trait
-/// can be derived automatically. See the [codegen
-/// documentation](https://github.com/diesel-rs/diesel/tree/master/diesel_codegen#derivequeryable)
-/// for more.
+/// can be derived automatically using `diesel_codegen`. This trait can only be derived for
+/// structs, not enums.
 pub trait Queryable<ST, DB> where
     DB: Backend + HasSqlType<ST>,
 {

diesel_codegen/README.md

@@ -1,2 +1,42 @@
-# This crate is in the process of being rewritten. The old readme can be found
-# [here](diesel_codegen_old)
+# Diesel Codegen
+
+This crate implements Diesel's procedural macros using the Macros 1.1 system. It
+requires nightly Rust from October 10, 2016 or later. For usage on stable
+Rust, see
+[`diesel_codegen_syntex`](https://github.com/diesel-rs/diesel/tree/master/diesel_codegen_syntex).
+
+Diesel Codegen provides custom derive implementations for
+[`Queryable`][queryable], [`Identifiable`][identifiable],
+[`Insertable`][insertable], [`AsChangeset`][as-changeset], and [`Associations`].
+It also provides the macros [`infer_schema!`][infer-schema],
+[`infer_table_from_schema!`][infer-table-from-schema], and
+[`embed_migrations!`][embed-migrations].
+
+[queryable]: http://docs.diesel.rs/diesel/query_source/trait.Queryable.html
+[identifiable]: http://docs.diesel.rs/diesel/associations/trait.Identifiable.html
+[as-changeset]: http://docs.diesel.rs/diesel/query_builder/trait.AsChangeset.html
+[infer-schema]: http://docs.diesel.rs/diesel/macro.infer_schema!.html
+[infer-table-from-schema]: http://docs.diesel.rs/diesel/macro.infer_table_from_schema!.html
+[embed-migrations]: http://docs.diesel.rs/diesel/macro.embed_migrations!.html
+
+# Using this crate
+
+First, add this crate to Cargo.toml as so:
+
+```toml
+diesel_codegen = { version = "0.8.0", features = ["postgres"] }
+```
+
+If you are using SQLite, be sure to specify `sqlite` instead of `postgres` in
+the `features` section.
+
+Next, at the root of your crate add:
+
+```rust
+#![feature(proc_macro)]
+
+#[macro_use] extern crate diesel_codegen;
+```
+
+See the documentation for each trait/macro for additional details and
+configuration options.