Add some documentation about common compiler error message types that users can encounter if something goes wrong #3556
Conversation
users can encounter if something goes wrong.
There was a problem hiding this comment.
Looks great to me! Some nits on grammar, but otherwise I think this was a fantastic idea. One question, though: where will this appear? Like... I imagine a lot of ppl show up in the issues page or gitter and ask about "what does this scary compiler message mean?" and you'll have to redirect them to this file.
Is there a way to get ahead of these questions? Like... being in lib.rs does that mean it will show up on the home page of the docs for diesel here? Or just generally wondering how ppl will even know that this documentation exists
| //! Consider using [`#[derive(Selectable)]`](derive@crate::prelude::Selectable) + | ||
| //! `#[diesel(check_for_backend(diesel::pg::Pg))]` |
There was a problem hiding this comment.
What value does using these macros provide?
There was a problem hiding this comment.
value in terms of diesel::pg::Pg? In that case it accepts a list of diesel backend types that are used for checking.
value in terms of improvements: It generates additional code that improves the compiler error message by pointing the the relevant field of the mismatch. See #3359 for details
|
Thanks for the review and the suggestions 👍. Will include that later in the PR.
This will appear in the API documentation in basically the linked location (just above the feature flag section). Additionally it might be a good idea to put a FAQ section into the readme and/or the web page that links this section (and others that answer other commonly questions). |
Ah I see it'll show up on this page: https://docs.rs/diesel/latest/diesel/ I think including it in a FAQ section in the |
weiznich
force-pushed
the
docs/how_to_read_error_messages
branch
from
a0a5ed8 to
5dad3d5
Compare
Co-authored-by: Steven Chu <stevenc1@gmail.com>
weiznich
force-pushed
the
docs/how_to_read_error_messages
branch
from
5dad3d5 to
87b8977
Compare
There are a few quite common error cases that generate large complicated looking messages, but that are quite easy to break down if the error message does not scare you away. This documentation section tries to give users a potential starting point where they need to look for the issue that causes the error message.