Document Diesel usage guidelines and edge cases

[killercup]

We don't (yet) have a good way to document general guidelines on how to use Diesel or, put another way, how we expect it to be used. There are a lot of implicit assumption and various edge cases to keep track of. For many, Diesel there are answers in this issue tracker, but the issues have been closed.

This meta issue wants to keep track of these undocumented pieces.

• How to write query builder return types using diesel::helper_types (#1037)
• What to keep in mind when using diesel_derive: Name-spacing and hygiene (#1032)
• When to use a table's dsl namespace: Only in functions dealing with one table (#1032)

If you want to help out, we'd love to get PRs to add more information to our API docs. The linked issues usually contain the necessary information, but feel free to ask on gitter for more details.

We might also want to move some of this to a new section of the website. Either a new guide on Best Practices or a good ol' FAQ page.

---

@killercup will try to update this issue semi-regularly. Ping him on Gitter or in the issue tracker if you have suggestions or questions.

[lancecarlson]

@killercup For the last one, perhaps adding language to end of this section would make sense?

http://docs.diesel.rs/diesel/macro.table.html#dsl

Something along the lines of: Only import this into the scope of a function you a building the query in otherwise it will pollute the namespace.

Perhaps an example could be provided that looked something like this:

// bad
use diesel_demo::schema::posts::dsl::*;
fn main() {
    // good
    use diesel_demo::schema::posts::dsl::*;
}

If you're cool with this, I'll make a PR.

[killercup]

@lancecarlson sounds good!