6.12 shows `!` syntax for _TraitImpl_ but never explains it

[tlyu]

6.12 (Implementations) shows syntax where ! can optionally precede TypePath. It looks like this is meant for negative implementations of auto traits? I think there should at least be a link to Chapter 11 (Special types and traits).

I'm willing to work on a pull request for this.

[ehuss]

Yea, this is a known issue, see #869. It's a bit unfortunate that unstable syntax isn't feature gated in the parser. It is not clear to me how the reference should handle that, since it doesn't document unstable features, but unstable syntax is stable via macros and conditional compliation. This one is particularly weird because it shows up in the std docs.

There's more information about the attempts to gate this in rust-lang/rust#65860, issue description at rust-lang/rust#65742 (comment), and rust-lang/rust#64672 (comment).

[tlyu]

I'm not sure I've found all of the relevant references, but it seems like the ! "never" type is still partially unstable, yet documented in the reference. Maybe we could adopt a similar strategy for negative traits?

[ehuss]

Never-type is a bit of an exception. There were attempts to stabilize it multiple times. Instead of removing it, adding it, removing it again, etc., we just left what is there with a note (and I think it is still somewhat relevant for function return types, see #945). It has been perpetually "just around the corner" (with recent updates as of just a few days ago, see rust-lang/lang-team#60), and hopefully it will get stabilized.

[tlyu]

Yea, this is a known issue, see #869. It's a bit unfortunate that unstable syntax isn't feature gated in the parser. It is not clear to me how the reference should handle that, since it doesn't document unstable features, but unstable syntax is stable via macros and conditional compliation. This one is particularly weird because it shows up in the std docs.

Thanks for the background information. It does seem like a difficult problem. However, if the syntax is not gated, we should document its existence. We already do in the grammar, but we should probably also mention that user code should not use it. Maybe also mention that it's used internally by libstd? As you say, it does already leak into the libstd docs.

Also, there's already text in Chapter 11 (Special types and traits) about negative trait implementations, so I think we could at least link to there from the grammar. (We could also make it more clear in Chapter 11 that negative trait implementations aren't stable and are internal to the standard library for now.)

Chapter 11 is also incomplete in that non-auto traits can have negative implementations (and some are required by Pin: rust-lang/rust#66544).