Some general remarks (I don't have bandwidth to take over review for this ATM):

• I wonder if we should explicitly delineate between lint level control mechanisms which are compiler-only, versus those part of the language (such as in-source lint level attributes).
• I'm not so sure the priority order is well-defined. See Support overriding warnings level for a specific lint via command line #113307 (comment) .
• Note that the ordering of compiler flags can matter! Some flags are "commutative" (in terms of observable final behavior) with respect to each other IIRC, while some flags aren't.
• (Unstable, not suitable for stable rustc book) there's also the --crate-attr flag, which can somewhat blur the line between compiler vs language.

Thanks for the feedback! I took a closer look and I think you're right. If that's the case, it might be best to just document the ordering for in-source lint level attributes, where the behavior is straightforward: the closer attribute takes precedence.

For what it's worth, the reason I made that distinction is because I feel like:

• Compiler flag mechanisms belong in the rustc book, but
• Language (in-source) attributes and the concept IMO belongs in the Reference.

What is a "global compiler configuration"?

Poor wording on my side, I meant options in the .cargo file, which is the same as CLI options, so I removed this part.

Wording nit:

Usually use sentence case for section titles.

I think the way this is presented is possibly confusing. The language doesn't differentiate between inner and outer attributes for lint levels. It just so happens that crate-level can only be specified by an inner attribute. But inner attributes can show up in many places. I would probably just say "attributes" here, since attributes just create an AST-hierarchy with the most-specific taking precedence.

The use of parentheses looks a little strange here to me, since force_warn(lint) isn't a valid syntax anywhere. How about just something like this?

I don't know what "normal configurations" are.

Also, this doesn't seem quite accurate to me. cap-lints takes precedence over forbid.
And in a sense it does matter where forbid is set, since it applies only to the AST-hierarchy below where it is set.

force-warn can only be set in one place (the CLI), though I'm not sure if this is trying to convey something about the order of CLI arguments?

This doesn't say how forbid and force-warn interact with one another.

It is a bit confusing for me. As far as I understood, for allow, deny, and warn whoever has the most-specific scope takes precedence. However, it is the opposite case for forbid and force-warn.

Even the ordering in the cli options, as mentioned in the book, for -A, -D, and -W which ever option comes last, takes place, but for --force-warn and -F which ever option comes first, takes place.

This section in general is feeling a little confusing to me.

Some specific comments:

• This introduces novel terms like "special lint level" and "standard lint level", but doesn't define what those are.
• force-warn doesn't really have a "scope" in the sense of the AST.

I'd like to dig in a little to where the confusion with the current documentation is coming from. And maybe @jieyouxu can chime in with their thoughts?

The existing documentation for force-warn I think pretty clearly specifies that it forces a lint to be at warning level, and it cannot be overridden by anything, including cap-lints.

The existing documentation for forbid specifies that it forces something to be an error, and cannot be overridden except by --cap-lints.

(I think it would be great to move these examples up to those sections, though.)

As a mental model for "forbid", I wouldn't think about it as "least specific scope" wins. The actual behavior is that attempts to override forbid in more specific scopes is an error. Thus, there cannot be any different levels in more specific scopes; they are not allowed. Other than that restriction, forbid is no different from deny.

So, I'm curious where it feels like things aren't being specified?
I notice in #124088 that it mentions confusion over how CLI -A -W -D relate to attributes. And it seems like it would be great to be more explicit about that in the via-compiler-flag section.

The issue also mentions CLI groups, but it seems like that is already covered?

The "warnings" group I would also agree can be confusing. However, it has strange behaviors that might actually be buggy, or at least not what people expect (see things like #118140, #75668, #91262). We do have a little documentation here, but I'm not sure how much more we can say before venturing into "this might be a bug" territory.

Can you clarify more about where the confusions with the existing docs might be, and what the goals are?

If I were to add a section summarizing priorities, I might write it something like this:

## Summary of priorities
In summary, the different lint controls and how the interact are:
1. [`--force-warn`](#force-warn) forces a lint to warning level, and takes precedence over attributes and all other CLI flag.
2. [`--cap-lints`](#capping-lints) sets the maximum level of a lint, and takes precedence over attributes and the `-A`, `-D`, `-W`, `-F` CLI flags.
3. [CLI level flags](#via-compiler-flag) take precedence over attributes.
 - The order of the flags matter; flags on the right take precedence over earlier flags.
4. Within the source, [attributes](#via-an-attribute) at a lower-level in the syntax tree take precedence over attributes at a higher level, or from a previous attribute on the same entity as listed in left-to-right source order.
 - The exception is once a lint is set to "forbid", it is an error to try to change its level except for `deny`, which is allowed inside a forbid context, but is ignored.
In terms of priority, [lint groups](groups.md) are treated as-if they are expanded to a list of all of the lints they contain. The exception is the `warnings` group which ignores attribute and CLI order and applies to all lints that would otherwise warn within the entity.

And I wouldn't add any other new sections, since I'd be reluctant to belabor the point. I do like adding the examples to the sections above, and the section on attributes should probably say something about the fourth point about ast-hierarchy precedence.

(Sorry, I have to stop right now due to time, but I think the above is accurate. Does that make sense to you?

I agree with the feedback here. Primarily, I think for this PR, we should restrict its scope to the more "well-specified" parts.

There are some interactions (like flag precedence and warnings) which are underspecified, which I wanted to eventually make the interactions well-defined or clarified through test coverage.

See #142610 for what I had in mind on how to properly specify this, backed with test coverage

Thanks for the review. Sorry for the late response. I agree, and I have updated accordingly.

The only change I made was in the --cap-lints section, as it does not make sense for -A to be there:

2. [`--cap-lints`](#capping-lints) sets the maximum level of a lint, and takes precedence over attributes as well as the `-D`, `-W`, and `-F` CLI flags.

This paragraph seems to be partially repeating the previous one? I'm uncertain what's intended here.

Similar to the comment above, force-warn isn't really in the AST-hierarchy. Its an external mechanism that imposes its will upon all others. It is similar to --cap-lints which is also an external mechnaism, but --force-warn wins over --cap-lints.

This section seems like a duplicate of the previous one? I'm not quite clear why this is being repeated.

As mentioned above, it's not that it takes precedence. It's that it prevents overriding the lint level (with the exception that --cap-lints and --force-warn are able to override it).

Be sure to use sentence case.

Suggestion: there is also --force-warn

Nit: this wording is IMO a bit confusing, this is moreso about lint level precedence, there are no "conflicts", and I don't think "strength" is a thing.

I agree with the feedback here. Primarily, I think for this PR, we should restrict its scope to the more "well-specified" parts.

There are some interactions (like flag precedence and warnings) which are underspecified, which I wanted to eventually make the interactions well-defined or clarified through test coverage.