Document new #[expect] attribute and reasons parameter (RFC 2383)

[xFrednet]

This PR is created in preparation to stabilize the lint_reasons feature. I hope this covers everything 🙃

Tracking issue: rust-lang/rust#54503

[xFrednet]

The CI will fail, until the #[feature(lint_reasons)] has been stabilized in rustc. Everything else should be ready 🙃

[ehuss]

I'm not sure the link to the RFC is particularly important here. There are also a few typos here (unfulfilled_lint_expectation (no s) and expextation). It is also not clear to me what it means by "currently doesn't allow", as it seems to allow it just fine:

#![feature(lint_reasons)]
#![expect(unfulfilled_lint_expectations)]

Produces:

warning: this lint expectation is unfulfilled
 --> src/lib.rs:2:11
  |
2 | #![expect(unfulfilled_lint_expectations)]
  |           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unfulfilled_lint_expectations)]` on by default
  = note: the `unfulfilled_lint_expectations` lint can't be expected and will always produce this message

It does seem like it is always a warning, even if unfulfilled_lint_expectations is triggered (which seems strange).
Is there some more context here?

Perhaps it could say something like:

Note: The behavior of #[expect(unfulfilled_lint_expectations)] is currently defined to always generate the unfulfilled_lint_expectations lint. This may change in the future.

Perhaps this should be clarified before it is stabilized?

[xFrednet]

Note: The behavior of #[expect(unfulfilled_lint_expectations)] is currently defined to always generate the unfulfilled_lint_expectations lint. This may change in the future.

Yes this is what I intended to say. The context sadly cannot be condensed to one link. This behavior was implemented in rust-lang/rust#94670. This has been discussed in the RFC PR (rust-lang/rfcs#2383 (comment)) with the suggestion to allow the unfulfilled_lint_expectations to be caught by outer expectations.

This can also be implemented in rustc. However, I decided against this for two reasons:

1. I didn't see a benefit. In the RFC Discussion, it was also said that there seems to be no use case for #[expect(unfulfilled_lint_expectations)]
2. Supporting #[expect(unfulfilled_lint_expectations)] would add a bunch of complexity. Currently, the lint is emitted at the item the attribute is attached to (For reasons regarding, incremental compilation and hash stability). To support such an expectation, we would need to either store the lint level and then order the expectations by which could fulfill which one or depend on the processing order which has caused some issues in the past. So, either solution would add complexity to the implementation without having an use case. We can also not simply emit the lint at the parent item due to the way lint levels are processed.

---

btw how did you add the (i) Note marker? I can sadly not see the MD text

[ehuss]

This sentence wasn't really clear to me what it meant. I might suggest breaking the example up into two parts. The first example can show where unfulfilled_lint_expectations is unfulfilled. Then, after that example, write a small paragraph and a second example that explains how changing the level of a lint within an expectation scope will override the expect attribute. Perhaps something like:

---

If the level of a lint is modified within an expect scope with a warn or deny attribute, then triggering that lint does not satisfy the expect attribute, and the unfulfilled_lint_expectations will also trigger. Similarly, squelching a lint with allow will also prevent the lint from being fulfilled.

---

This behavior seems kinda confusing to me, and it is not really clear to me how it is working, or if that is really intended behavior?

I might also include some text explaining the interaction with forbid, since that also isn't entirely clear to me. I believe it is something like "if a lint has previously been marked with forbid, then it is not allowed to use the expect attribute with that lint".

[xFrednet]

This behavior seems kinda confusing to me, and it is not really clear to me how it is working, or if that is really intended behavior?

This is intended behavior, see rust-lang/rust#54503 (comment)

I've added more examples and documentation. 🙃

[xFrednet]

With rust-lang/rust#115980 (comment) the semantics of the #[expect] attribute have been decided. I've reworked some parts of the documentation, to make the semantics clearer according to the decision.

The CI is currently failing, since the feature is not yet stabilized in rustc. I'll work on that part next.

[ehuss]

In what way might this change?

[xFrednet]

The original RFC had a discussion about expecting the unfulfilled_lint_expectations lint, but never came up with a valid use case. The current behavior is the result of the way that rustc emits lints. If someone comes up with a valid use case, I think it would be valid to change the behavior of expecting this specific lint, but I honestly can't think of one.

Maybe it would be better, to remove the last sentence? (I'll do that in the typo fix commit)

[xFrednet]

rust-lang/rust#120924 has been merged and this feature will be part of Rust 1.81 🎉

This PR should be ready for review. We'll have to wait one nightly to allow the example code blocks to compile in CI. I'll rebase it tomorrow. I'll be gone over the weekend, but can gat back to it afterwards :D

[xFrednet]

I've rebased and the CI is green 🎉 It should be ready for review an maybe merge :D

[ehuss]

Thanks! I pushed up a small fix.