Add some comments and rename the option to -Zcache-derive-macros

Author: Kobzol

compiler/rustc_ast/src/tokenstream.rs

@@ -650,6 +650,8 @@ impl<H: std::hash::Hasher> SpanEncoder for HashEncoder<H> {
     }
 }
 
+/// TokenStream needs to be hashable because it is used as a query key for caching derive macro
+/// expansions.
 impl Hash for TokenStream {
     fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
         Encodable::encode(self, &mut HashEncoder { hasher: state });

compiler/rustc_expand/src/proc_macro.rs

@@ -145,7 +145,8 @@ impl MultiItemModifier for DeriveProcMacro {
 
             // FIXME(pr-time): Is this the correct way to check for incremental compilation (as
             // well as for `cache_proc_macros`)?
-            if tcx.sess.opts.incremental.is_some() && tcx.sess.opts.unstable_opts.cache_proc_macros
+            if tcx.sess.opts.incremental.is_some()
+                && tcx.sess.opts.unstable_opts.cache_derive_macros
             {
                 // FIXME(pr-time): Just using the crate hash to notice when the proc-macro code has
                 // changed. How to *correctly* depend on exactly the macro definition?
@@ -197,6 +198,7 @@ impl MultiItemModifier for DeriveProcMacro {
     }
 }
 
+/// Provide a query for computing the output of a derive macro.
 pub(super) fn provide_derive_macro_expansion<'tcx>(
     tcx: TyCtxt<'tcx>,
     key: (LocalExpnId, Svh, &'tcx TokenStream),

compiler/rustc_middle/src/query/mod.rs

@@ -165,9 +165,14 @@ pub use plumbing::{IntoQueryParam, TyCtxtAt, TyCtxtEnsureDone, TyCtxtEnsureOk};
 // Queries marked with `fatal_cycle` do not need the latter implementation,
 // as they will raise an fatal error on query cycles instead.
 rustc_queries! {
+    /// Caches the expansion of a derive proc macro, e.g. `#[derive(Serialize)]`.
+    /// The key is:
+    /// - A unique key corresponding to the invocation of a macro.
+    /// - Strict Version Hash of a crate.
+    /// - Token stream which serves as an input to the macro.
+    ///
+    /// The output is the token stream generated by the proc macro.
     query derive_macro_expansion(key: (LocalExpnId, Svh, &'tcx TokenStream)) -> Result<&'tcx TokenStream, ()> {
-        // eval_always
-        // no_hash
         desc { "expanding a derive (proc) macro" }
         cache_on_disk_if { true }
     }

tests/incremental/derive_macro_expansion/proc_macro_unchanged.rs

@@ -8,24 +8,23 @@
 
 //@ aux-build:derive_nothing.rs
 //@ revisions:cfail1 cfail2
-//@ compile-flags: -Z query-dep-graph -Zcache-proc-macros=true
+//@ compile-flags: -Z query-dep-graph -Zcache-derive-macros=true
 //@ build-pass
 
 #![feature(rustc_attrs)]
 #![feature(stmt_expr_attributes)]
 #![allow(dead_code)]
 #![crate_type = "rlib"]
-
-#![rustc_partition_codegened(module="proc_macro_unchanged-foo", cfg="cfail1")]
+#![rustc_partition_codegened(module = "proc_macro_unchanged-foo", cfg = "cfail1")]
 // #![rustc_partition_codegened(module="proc_macro_unchanged-foo", cfg="cfail2")]
 
 // `foo::nothing_mod` is created by the derive macro and doesn't change
-// BUG: this yields the same result with `-Zcache-proc-macros=false` (i.e., uncached),
+// BUG: this yields the same result with `-Zcache-derive-macros=false` (i.e., uncached),
 // not sure how to do this correctly.
-#![rustc_partition_reused(module="proc_macro_unchanged-foo-nothing_mod", cfg="cfail2")]
+#![rustc_partition_reused(module = "proc_macro_unchanged-foo-nothing_mod", cfg = "cfail2")]
 
- #[macro_use]
- extern crate derive_nothing;
+#[macro_use]
+extern crate derive_nothing;
 
 pub mod foo {
     #[derive(Nothing)]