Avoid duplicated query modifier comments.

By removing the ones in `compiler/rustc_middle/src/queries.rs`, and
making `compiler/rustc_middle/src/query/modifiers.rs` the single
source of truth.

Author: nnethercote

compiler/rustc_middle/src/queries.rs

@@ -23,27 +23,11 @@
 //! ## Query Modifiers
 //!
 //! Query modifiers are special flags that alter the behavior of a query. They are parsed and processed by the `rustc_macros`
-//! The main modifiers are:
 //!
-//! - `desc { ... }`: Sets the human-readable description for diagnostics and profiling. Required
-//!   for every query. The block should contain a `format!`-style string literal followed by
-//!   optional arguments. The query key identifier is available for use within the block, as is
-//!   `tcx`.
-//! - `arena_cache`: Use an arena for in-memory caching of the query result.
-//! - `cache_on_disk_if { ... }`: Cache the query result to disk if the provided block evaluates to
-//!   true. The query key identifier is available for use within the block, as is `tcx`.
-//! - `cycle_delay_bug`: If a dependency cycle is detected, emit a delayed bug instead of aborting immediately.
-//! - `cycle_stash`: If a dependency cycle is detected, stash the error for later handling.
-//! - `no_hash`: Do not hash the query result for incremental compilation; just mark as dirty if recomputed.
-//! - `anon`: Make the query anonymous in the dependency graph (no dep node is created).
-//! - `eval_always`: Always evaluate the query, ignoring its dependencies and cached results.
-//! - `depth_limit`: Impose a recursion depth limit on the query to prevent stack overflows.
-//! - `separate_provide_extern`: Use separate provider functions for local and external crates.
-//! - `feedable`: Allow the query result to be set from another query ("fed" externally).
+//! For the list of modifiers, see
+//! [`rustc_middle/src/query/modifiers.rs`](https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_middle/src/query/modifiers.rs).
 //!
-//! For the up-to-date list, see the `QueryModifiers` struct in
-//! [`rustc_macros/src/query.rs`](https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_macros/src/query.rs)
-//! and for more details in incremental compilation, see the
+//! For more details on incremental compilation, see the
 //! [Query modifiers in incremental compilation](https://rustc-dev-guide.rust-lang.org/queries/incremental-compilation-in-detail.html#query-modifiers) section of the rustc-dev-guide.
 //!
 //! ## Query Expansion and Code Generation

compiler/rustc_middle/src/query/modifiers.rs

@@ -4,48 +4,68 @@
 //! modifier names in the query list, and to allow find-all-references to list
 //! all queries that use a particular modifier.
 #![allow(unused, non_camel_case_types)]
-// FIXME: Update and clarify documentation for these modifiers.
 
 // tidy-alphabetical-start
 //
 /// # `anon` query modifier
 ///
-/// Generate a dep node based on the dependencies of the query
+/// Generate a dep node based not on the query key, but on the query's dependencies.
 pub(crate) struct anon;
 
 /// # `arena_cache` query modifier
 ///
-/// Use this type for the in-memory cache.
+/// Query return values must impl `Copy` and be small, but some queries must return values that
+/// doesn't meet those criteria. Queries marked with this modifier have their values allocated in
+/// an arena and the query returns a reference to the value. There are two cases.
+/// - If the provider function returns `T` then the query will return `&'tcx T`.
+/// - If the provider function returns `Option<T>` then the query will return `Option<&'tcx T>`.
+///
+/// The query plumbing takes care of the arenas and the type manipulations.
 pub(crate) struct arena_cache;
 
-/// # `cache_on_disk_if` query modifier
+/// # `cache_on_disk_if { ... }` query modifier
+///
+/// Cache the query result to disk if the provided block evaluates to true. The query key
+/// identifier is available for use within the block, as is `tcx`.
 ///
-/// Cache the query to disk if the `Block` returns true.
+/// The decision to use this modifier comes down to whether it helps performance. Not all query
+/// results need to be saved to disk. In particular, caching values from upstream crates is
+/// pointless because they are already available in the upstream crate’s metadata.
 pub(crate) struct cache_on_disk_if;
 
 /// # `cycle_delay_bug` query modifier
 ///
-/// A cycle error results in a delay_bug call
+/// If a dependency cycle is detected, emit a delayed bug instead of a normal error.
 pub(crate) struct cycle_delay_bug;
 
 /// # `cycle_stash` query modifier
 ///
-/// A cycle error results in a stashed cycle error that can be unstashed and canceled later
+/// If a dependency cycle is detected, stash the error for later handling.
 pub(crate) struct cycle_stash;
 
 /// # `depth_limit` query modifier
 ///
-/// Whether the query has a call depth limit
+/// Impose a recursion call depth limit on the query to prevent stack overflow.
 pub(crate) struct depth_limit;
 
-/// # `desc` query modifier
+/// # `desc { ... }` query modifier
 ///
-/// The description of the query. This modifier is required on every query.
+/// The human-readable description of the query, for diagnostics and profiling. Required for every
+/// query. The block should contain a `format!`-style string literal followed by optional
+/// arguments. The query key identifier is available for use within the block, as is `tcx`.
 pub(crate) struct desc;
 
 /// # `eval_always` query modifier
 ///
-/// Always evaluate the query, ignoring its dependencies
+/// Queries with this modifier do not track their dependencies, and are treated as always having a
+/// red (dirty) dependency instead. This is necessary for queries that interact with state that
+/// isn't tracked by the query system.
+///
+/// It can also improve performance for queries that are so likely to be dirtied by any change that
+/// it's not worth tracking their actual dependencies at all.
+///
+/// As with all queries, the return value is still cached in memory for the rest of the compiler
+/// session.
 pub(crate) struct eval_always;
 
 /// # `feedable` query modifier
@@ -55,12 +75,12 @@ pub(crate) struct feedable;
 
 /// # `no_hash` query modifier
 ///
-/// Don't hash the result, instead just mark a query red if it runs
+/// Do not hash the query result for incremental compilation; just mark it as dirty if recomputed.
 pub(crate) struct no_hash;
 
 /// # `separate_provide_extern` query modifier
 ///
-/// Use a separate query provider for local and extern crates
+/// Use separate query provider functions for local and extern crates.
 pub(crate) struct separate_provide_extern;
 
 // tidy-alphabetical-end