Add the #[diagnostic] attribute namespace and the #[diagnostic::on_unimplemented] feature to the reference

[weiznich]

As requested here

[weiznich]

I'm not really sure what needs to be done to address the CI errors as the name space is in fact currently unstable but it was requested during the stablization PR to fill this PR.

[ehuss]

The CI errors are fine, this won't be merged until the stabilization hits nightly which should resolve them.

[ehuss]

Thanks!

[ehuss]

We try to avoid using the phrase "the compiler" too much, since the reference is really focused on the language and not how it is implemented. There are also ambiguities to be careful of in terms of wording things like "user" or "error".

Suggested change

The `#[diagnostic]` attribute namespace is meant to provide a home for attribute that allow users to influence error messages emitted by the compiler. The compiler is not guaranteed to use any of this hints, however it should accept any (non-)existing attribute in this namespace and potentially emit lint-warnings for unused attributes and options. This is meant to allow discarding certain attributes/options in the future to allow fundamental changes to the compiler without the need to keep then non-meaningful options working.

The `#[diagnostic]` attribute namespace is meant to provide a home for attributes to influence compile-time error messages. The hints provided by these attributes are not guaranteed to be used. Unknown attributes in this namespace are accepted, though they may emit warnings for unused attributes. Additionally, invalid input to known attributes will typically be a warning (see the attribute definitions for details). This is meant to allow adding or discarding attributes and changing inputs in the future to allow changes without the need to keep the non-meaningful attributes or options working.

Also, can you break lines after periods? That makes it easier to view diffs and refer to specific sentences.

[ehuss]

I think it would be good to keep this as a single rust block so that the example can stand alone and actually generate the warning (for example, if someone presses the play button).

[ehuss]

The #[diagnostic::on_unimplemented] attribute is allowed to appear on trait definitions.

This part doesn't seem quite correct, since it appears to be allowed to appear anywhere an attribute is allowed.

---

Some suggestions to try to be direct about the meaning of the attribute, exactly when it would trigger, and the allowed input for the attribute:

Suggested change

The `#[diagnostic::on_unimplemented]` attribute is allowed to appear on trait definitions. This allows crate authors to hint the compiler to emit a specific worded error message if a certain trait is not implemented. The hinted message is supposed to replace the otherwise emitted error message. For the `#[diagnostic::on_unimplemented]` attribute the following options are implemented:

The `#[diagnostic::on_unimplemented]` attribute is allowed to appear on trait definitions. This attribute hints to the compiler to supplement the error message that would normally be generated in scenarios where the trait is required but not implemented on a type. The attribute uses the [_MetaListNameValueStr_] syntax to specify its inputs, though any malformed input to the attribute is not considered as an error to provide both forwards and backwards compatibility. The following keys have the given meaning:

[compiler-errors]

This can/should get merged now

[ehuss]

If this is the actual intention here, then I think an edit like the following would make sense:

Suggested change

	All three options accept a string as an argument.
	The text in the string may contain the following format parameters which provide substitutions in the generated message:
	All three options accept a string as an argument, interpreted using the same formatting as a [`std::fmt`] string.
	Format parameters with the given named parameter will be replaced with the following text:

[weiznich]

That sound reasonable for me and that mirrors the actual implementation after the fix implemented in rust-lang/rust#122402

[ehuss]

Suggested change

	Invalid format strings may generate a warning, but are otherwise allowed, but may not display as intended.
	Format specifiers may generate a warning, but are otherwise ignored.

[weiznich]

That sound reasonable for me and that mirrors the actual implementation after the fix implemented in rust-lang/rust#122402

[ehuss]

Thanks!