Documentation (eg. of "-> !")

I have seen some code using -> ! as a function return type but I had hell of a time trying to find out what it means ("nothing" type). Could the docs search engine perhaps be made to react to meaningful sub-strings of Rust syntax, like this one? At the moment it does not, so it is impossible to find out any information about it. Unless you have read and committed to memory the entire documentation manual, I guess.

The never type is new and not stable quite yet. It is in the std docs and the reference.

You can find it listed under "primitives" from the std index page or by doing a search for !

Yes, searching for ! is how I eventually managed to find it but my earlier more specific search for "-> !" lead nowhere. The point is, if all kinds of linters can do a fairly decent job in similar circumstances, why not the main documentation search engine?

I'm not sure what do you mean by "more specific". Should we have separate documentation for "type as return type"?

I mean I initially avoided searching for '!' because I knew it would come up with pages and pages of all the macros and pragmas and asserts and negation operators. So the natural thing is to narrow down the search to the limited circumstances of the appearance of this '!'. The difference is that I am talking about the syntactic context but you are only acknowledging the semantic one.

The book also has a page: https://doc.rust-lang.org/stable/book/appendix-02-operators.html

Indeed it does but nowhere therein is "-> !". I mean it should not require deep AI to be able to say, as you no doubt can, oh yes, these three characters mean: return a "never" type?

That's because it's two different things, put together:


(Also, for completeness, the book talks about this exact subject here https://doc.rust-lang.org/stable/book/ch19-04-advanced-types.html?#the-never-type-that-never-returns though I know the point is about searching, but maybe including a link here will help!)

Granted. I am just making an appeal for some bottom-up parsing capability in the search engine. Your top-down approach is only meaningful if you already know it all, as you do. For example, when you already know that ! is not only all those above mentioned things but also a type in its own right. However, this is not something that the beginners know, that is why they are trying to search it up :roll_eyes:

I am sure I could come up with lots of other examples of mysterious Rust incantations where to find their documentation you must already know all about them.

Yes, I am not trying to say that enhancing search has no value. But, in case, for example, someone searches google and finds this thread, I thought it would be worth putting the answer here as well.

1 Like

That would be cool.

Copy and paste a line of Rust code into a search box, get links to the descriptions of every syntactic element used in the line, in the reference and/or elsewhere.

Example: I was recently offered this function signature as a solution to some problem:

fn work(&mut self, p: i64, mut pr: Iter<'_, i64>) {

I was scratching my head wondering what that default life time was doing on the 'Iter'. Churning around all the documentation for 'iter', 'iterator', 'Iter' I could find was not getting me anywhere.

Then I decided to ask the compiler, I removed the ''_'. Lo, it turns out I don't need it there at all !

2 Likes

The lint isn't enable by default yet, but removing the '_ is depreciated because it hides the fact that the struct contains borrowed data. The only difference between Iter<i64> and Iter<'_, i64> is how much information they give to someone reading the code.

Here's the tracking issue for enabling it by default.

Thanks. Those words make it all very clear now.

I was quite happy without the '<'_,'. Too much line noise make me go cross-eyed and it harder to read.

Are you saying that clippy will soon start demanding I add more line noise all over my code?

Edit: Hmmm...

$ export RUSTFLAGS="$RUSTFLAGS -W rust_2018_idioms"
$ time cargo clippy
...
           ^^^^^^^^^ help: indicate the anonymous lifetime: `Iter<'_, i64>`
...

Seems so.

1 Like

I wouldn't call an anonymous lifetime line noise; it's important to keep in mind it's lifetime (as in that of the object whose lifetime you chose to omit) is bounded in some way and the input/output may require you to select parameters which fit this constraint. It may also be clearer for messages where the compiler can explicitly reference the name '_ in an error instead of giving you a message which uses some kind of more anonymous lifetime defined by the compiler.

1 Like