Deny missing docs

[killercup]

Diesel should have a thoroughly documented API, and I'd like it to compile with #[deny(missing_docs)]. To make this even harder better, I'd like it to have an example for each major¹ public item.

What needs documenting

• Here's a list² of the items that currently miss documentation: https://gist.github.com/killercup/baf6975ea40d70cd278823a6af9bc05d
• Many items already have doc comments and thus don't show up in this list, but they could use some more extensive explanations or examples, so feel free to make PRs for those as well.
• Module-level documentation can always use more examples
• Other good documentation PRs would be adding a CONTRIBUTING.md, and README.md files for all crate subfolders to (shortly) describe their purpose. (This will also make contributing to this issue easier!)

If you want to help

A good size for pull requests is "one pull request per file". This will reduce git churn and it is in general easier to review short PRs.

I would suggest doing the following:

1. Clone this repository
2. Set up your system so the tests run without errors, feel free to ask on Gitter if you have problems
3. Choose a file/module/item you want to add documentation to, and add #![deny(missing_docs)] to it (or #[deny(missing_docs)] for items like structs or traits)
4. Write nice documentation in easy to understand but precise English

• Read the official book's chapter on documentation if you haven't yet
• Feel free to follow these guidelines for formatting.
• If you add code examples, make sure they compile and run, just like test. Have a look at existing doc tests or ask on Gitter if you need help.

5. Ensure your code compiles with newly added documentation.
6. Open a PR on this repo and refer to this issue

---

¹ definition of 'major public item' pending, suggestions welcome 😄
² generated with (get rq with cargo install record-query)

cargo +nightly rustc --features 'postgres sqlite chrono unstable' \
  -- -D missing_docs --error-format json 2>&1 | \
  grep '^{' | \
  rq -jH 'filter [level, error] |
    flatMap spans |
    map (s) => { {file: `${s.file_name}:${s.line_start}`, text: s.text[0].text.trim()} } |
    uniqBy file |
    map (x) => { `${x.file} ${x.text}` }'

[mattjmcnaughton]

@killercup I'd love to take a stab at this if possible (first commit in Rust)! I've modified the code to include the #![deny(missing_docs)] and am happy to submit a pr for that. Were you also envisioning this diff fixing all of those items missing documentation as well?

[killercup]

first commit in Rust

Wow, that's amazing, @mattjmcnaughton!

Adding the deny itself will just make it not compile any more until all items in that list have doc comments. So we'll have to wait a bit before we can add this. :) Locally, you could also use #[warn(missing_docs)] to let the compiler give you a warning for all the undocumented public items in the code base (basically my list).

That's a lot of items to write documentation for, so I it makes sense to have a lot of smaller PRs adding docs for singular modules or traits.

Oh, and I totally forgot to link to these guidelines to keep the doc comment style consistent. (Not that I want each doc comment as extensive as the examples in there, though! Please let me know if you have suggestions to improve these guidelines.)

[sgrif]

Were you also envisioning this diff fixing all of those items missing documentation as well?

Definitely don't submit one PR fixing all of the documented items. One PR per file is about the right size. We can't accept a PR that adds #![deny(missing_docs)] until after the documented items are fixed.

[mattjmcnaughton]

Sounds like a plan (and thank you for the quick response)! As I understand the code, and as I get the change, I'll make some separate prs with the documentation changes, and when the documented items are fixed, I'll make a pr that adds #![deny(missing_docs)].

[killercup]

Exactly. And thank you! Since there are a lot of items to document, this does not need to (and probably should not) be a one person job. If more people want to help, I'll add a check list here to track what has already been documented. If you have any questions regarding the code or the API to document, feel free to drop by our Gitter room :) Matt McNaughton <notifications@github.com> schrieb am Sa. 7. Jan. 2017 um 03:41:

…

Sounds like a plan (and thank you for the quick response)! As I understand the code, and as I get the change, I'll make some separate prs with the documentation changes, and when the documented items are fixed, I'll make a pr that adds #![deny(missing_docs)]. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#563 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABOXxNUaUBr9jJUyekDKsLrBQW5Yvd7ks5rPvt1gaJpZM4LYwv1> .

[stuartellis]

I'm new to Rust, but I'd be happy to help with this.

[killercup]

I just added a few more details on how contribute to the issue description: #563 (comment)

[stuartellis]

@killercup - Thank you for that.

@mattjmcnaughton - FWIW, I think that I'll start with just CONTRIBUTING.md and README.md files before trying anything more in-depth myself.

[stuartellis]

Just to say that I am not going to be able to work on this, unfortunately (too many projects, something has to give).

[ericho]

Sent a very simple (and probably wrong) PR #592

[killercup]

Thank you! Every small contribution counts! Don't worry if it's not perfect at your first try; that's what code review is for! We'll get there together :) Erich Cordoba <notifications@github.com> schrieb am Do. 26. Jan. 2017 um 07:36:

…

Sent a very simple (and probably wrong) PR #592 <#592> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#563 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABOX1kJnAqU8PzmyYqmzlwtx_3sNFEtks5rWD7sgaJpZM4LYwv1> .

[sgrif]

Y'all need to review my open PRs so I can close this. ;P