"Identifier" column in table macro results in "Missing lifetime specifier"

[spease]

I was able to fix this using #[sql_name=“...”] but the error is not clear about what's really going on, and I found sql_name by searching through tickets, not through official documentation.

This seems like the sort of thing someone could get stuck on.

It was Nullable type if relevant.

[weiznich]

There is not much we can do about this. The table! macro is just a plain macro_rules macro that gives us no way to emit custom error messages.

The documentation of the table! macro already mentions #[sql_name="…"] so I'm quite unsure what else we could do to improve this. In my opinion the only improvement that could be done is to add more documentation on this. The questions is where and what.

[spease]

The serde documentation does a good job of enumerating attributes: https://serde.rs/ In general one problem I've run into has been understanding what the diesel API is. I've been using the generated documentation, and it seems to lack descriptive text for many things, eg load vs get_results.

…

On Apr 20, 2018, at 02:54, Georg Semmler ***@***.***> wrote: There is not much we can do about this. The table! macro is just a plain macro_rules macro that gives us no way to emit custom error messages. The documentation of the table! macro already mentions #[sql_name="…"] so I'm quite unsure what else we could do to improve this. In my opinion the only improvement that could be done is to add more documentation on this. The questions is where and what. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

[sgrif]

I found sql_name by searching through tickets, not through official documentation.

sql_name is definitely documented in the documentation for the table! macro. http://docs.diesel.rs/diesel/macro.table.html

The serde documentation does a good job of enumerating attributes:

Diesel has a much larger API surface than serde. They're able to compress their attributes into a handful of pages because they are all related to either Serialize and Deserialize. By contrast, Diesel has 10 derives, and we aren't even talking about a derive. For Diesel, I think it makes much more sense to document attributes on the trait being derived, or in this case, on the macro that's being used.

With all of that said, this was a poor interaction. The reason that this problem occurred is that we have an internal type called Identifier, which is the type of QuerySource::FromClause that we generate for your table. This is actually essentially duplicate of #851.

While we have 0 control over the error message in this case, we could probably avoid the error entirely by referencing Identifier through a qualified path, and avoiding importing it. We've paid less attention to importing types/traits here, since it's so uncommon to have a capitalized column. But we can definitely fix this specific case.

[spease]

I didn't realize there were that many derives - I've seen FromSql and ToSql, and I think there's a AsExpression trait that it looked like I had to use with them. However, in general, I've had to do a lot of digging through source code to understand how to do things, more digging than I would expect most people would do before they give up. There seems to be a sore deficit of application-related examples.

In general, I'd try to keep an "interface" (whatever that may mean) as simple as possible, but if it has to be complex, I'd definitely expect to need a fair amount of documentation. In general I'd expect a larger API would require more specialized documentation, not less (that being one reason I'd try to keep it as small as possible ;) ).

I understand you guys have limited time and probably aren't being paid, I'm just a little worried about the balance of functionality to documentation. There's a lot of functionality that exists, I suspect I can do pretty much everything I want with diesel, but it's often very difficult to figure out how.

[sgrif]

It's an ongoing project. You can always feel free to ask in gitter for help, that's often how we identify gaps in the documentation