Rollup merge of #90407 - pierwill:edit-rustc-incremental-docs, r=cjgillot

Document all public items in `rustc_incremental`

Also:

- Review and edit current docs
- Enforce documentation for the module.

compiler/rustc_incremental/src/assert_dep_graph.rs

@@ -52,6 +52,7 @@ use std::env;
 use std::fs::{self, File};
 use std::io::{BufWriter, Write};
 
+#[allow(missing_docs)]
 pub fn assert_dep_graph(tcx: TyCtxt<'_>) {
     tcx.dep_graph.with_ignore(|| {
         if tcx.sess.opts.debugging_opts.dump_dep_graph {
@@ -262,6 +263,7 @@ fn dump_graph(query: &DepGraphQuery) {
     }
 }
 
+#[allow(missing_docs)]
 pub struct GraphvizDepGraph<'q>(FxHashSet<&'q DepNode>, Vec<(&'q DepNode, &'q DepNode)>);
 
 impl<'a, 'q> dot::GraphWalk<'a> for GraphvizDepGraph<'q> {

compiler/rustc_incremental/src/assert_module_sources.rs

@@ -29,6 +29,7 @@ use rustc_session::cgu_reuse_tracker::*;
 use rustc_span::symbol::{sym, Symbol};
 use std::collections::BTreeSet;
 
+#[allow(missing_docs)]
 pub fn assert_module_sources(tcx: TyCtxt<'_>) {
     tcx.dep_graph.with_ignore(|| {
         if tcx.sess.opts.incremental.is_none() {

compiler/rustc_incremental/src/lib.rs

@@ -1,5 +1,6 @@
 //! Support for serializing the dep-graph and reloading it.
 
+#![deny(missing_docs)]
 #![doc(html_root_url = "https://doc.rust-lang.org/nightly/nightly-rustc/")]
 #![feature(in_band_lifetimes)]
 #![feature(let_else)]

compiler/rustc_incremental/src/persist/fs.rs

@@ -133,21 +133,26 @@ const QUERY_CACHE_FILENAME: &str = "query-cache.bin";
 // case-sensitive (as opposed to base64, for example).
 const INT_ENCODE_BASE: usize = base_n::CASE_INSENSITIVE;
 
+/// Returns the path to a session's dependency graph.
 pub fn dep_graph_path(sess: &Session) -> PathBuf {
     in_incr_comp_dir_sess(sess, DEP_GRAPH_FILENAME)
 }
+/// Returns the path to a session's staging dependency graph.
+///
+/// On the difference between dep-graph and staging dep-graph,
+/// see `build_dep_graph`.
 pub fn staging_dep_graph_path(sess: &Session) -> PathBuf {
     in_incr_comp_dir_sess(sess, STAGING_DEP_GRAPH_FILENAME)
 }
-
 pub fn work_products_path(sess: &Session) -> PathBuf {
     in_incr_comp_dir_sess(sess, WORK_PRODUCTS_FILENAME)
 }
-
+/// Returns the path to a session's query cache.
 pub fn query_cache_path(sess: &Session) -> PathBuf {
     in_incr_comp_dir_sess(sess, QUERY_CACHE_FILENAME)
 }
 
+/// Locks a given session directory.
 pub fn lock_file_path(session_dir: &Path) -> PathBuf {
     let crate_dir = session_dir.parent().unwrap();
 
@@ -166,23 +171,35 @@ pub fn lock_file_path(session_dir: &Path) -> PathBuf {
     crate_dir.join(&directory_name[0..dash_indices[2]]).with_extension(&LOCK_FILE_EXT[1..])
 }
 
+/// Returns the path for a given filename within the incremental compilation directory
+/// in the current session.
 pub fn in_incr_comp_dir_sess(sess: &Session, file_name: &str) -> PathBuf {
     in_incr_comp_dir(&sess.incr_comp_session_dir(), file_name)
 }
 
+/// Returns the path for a given filename within the incremental compilation directory,
+/// not necessarily from the current session.
+///
+/// To ensure the file is part of the current session, use [`in_incr_comp_dir_sess`].
 pub fn in_incr_comp_dir(incr_comp_session_dir: &Path, file_name: &str) -> PathBuf {
     incr_comp_session_dir.join(file_name)
 }
 
-/// Allocates the private session directory. The boolean in the Ok() result
-/// indicates whether we should try loading a dep graph from the successfully
-/// initialized directory, or not.
-/// The post-condition of this fn is that we have a valid incremental
-/// compilation session directory, if the result is `Ok`. A valid session
+/// Allocates the private session directory.
+///
+/// If the result of this function is `Ok`, we have a valid incremental
+/// compilation session directory. A valid session
 /// directory is one that contains a locked lock file. It may or may not contain
 /// a dep-graph and work products from a previous session.
-/// If the call fails, the fn may leave behind an invalid session directory.
+///
+/// This always attempts to load a dep-graph from the directory.
+/// If loading fails for some reason, we fallback to a disabled `DepGraph`.
+/// See [`rustc_interface::queries::dep_graph`].
+///
+/// If this function returns an error, it may leave behind an invalid session directory.
 /// The garbage collection will take care of it.
+///
+/// [`rustc_interface::queries::dep_graph`]: ../../rustc_interface/struct.Queries.html#structfield.dep_graph
 pub fn prepare_session_directory(
     sess: &Session,
     crate_name: &str,
@@ -661,6 +678,7 @@ fn is_old_enough_to_be_collected(timestamp: SystemTime) -> bool {
     timestamp < SystemTime::now() - Duration::from_secs(10)
 }
 
+/// Runs garbage collection for the current session.
 pub fn garbage_collect_session_directories(sess: &Session) -> io::Result<()> {
     debug!("garbage_collect_session_directories() - begin");
 

compiler/rustc_incremental/src/persist/load.rs

@@ -18,13 +18,24 @@ use super::work_product;
 type WorkProductMap = FxHashMap<WorkProductId, WorkProduct>;
 
 #[derive(Debug)]
+/// Represents the result of an attempt to load incremental compilation data.
 pub enum LoadResult<T> {
-    Ok { data: T },
+    /// Loading was successful.
+    Ok {
+        #[allow(missing_docs)]
+        data: T,
+    },
+    /// The file either didn't exist or was produced by an incompatible compiler version.
     DataOutOfDate,
-    Error { message: String },
+    /// An error occured.
+    Error {
+        #[allow(missing_docs)]
+        message: String,
+    },
 }
 
 impl<T: Default> LoadResult<T> {
+    /// Accesses the data returned in [`LoadResult::Ok`].
     pub fn open(self, sess: &Session) -> T {
         // Check for errors when using `-Zassert-incremental-state`
         match (sess.opts.assert_incr_state, &self) {
@@ -99,6 +110,7 @@ pub enum MaybeAsync<T> {
 }
 
 impl<T> MaybeAsync<LoadResult<T>> {
+    /// Accesses the data returned in [`LoadResult::Ok`] in an asynchronous way if possible.
     pub fn open(self) -> LoadResult<T> {
         match self {
             MaybeAsync::Sync(result) => result,
@@ -109,6 +121,7 @@ impl<T> MaybeAsync<LoadResult<T>> {
     }
 }
 
+/// An asynchronous type for computing the dependency graph.
 pub type DepGraphFuture = MaybeAsync<LoadResult<(SerializedDepGraph, WorkProductMap)>>;
 
 /// Launch a thread and load the dependency graph in the background.

compiler/rustc_incremental/src/persist/save.rs

@@ -13,9 +13,13 @@ use super::file_format;
 use super::fs::*;
 use super::work_product;
 
-/// Save and dump the DepGraph.
+/// Saves and writes the [`DepGraph`] to the file system.
 ///
-/// No query must be invoked after this function.
+/// This function saves both the dep-graph and the query result cache,
+/// and drops the result cache.
+///
+/// This function should only run after all queries have completed.
+/// Trying to execute a query afterwards would attempt to read the result cache we just dropped.
 pub fn save_dep_graph(tcx: TyCtxt<'_>) {
     debug!("save_dep_graph()");
     tcx.dep_graph.with_ignore(|| {
@@ -75,6 +79,7 @@ pub fn save_dep_graph(tcx: TyCtxt<'_>) {
     })
 }
 
+/// Saves the work product index.
 pub fn save_work_product_index(
     sess: &Session,
     dep_graph: &DepGraph,
@@ -139,6 +144,12 @@ fn encode_query_cache(tcx: TyCtxt<'_>, encoder: &mut FileEncoder) -> FileEncodeR
     tcx.sess.time("incr_comp_serialize_result_cache", || tcx.serialize_query_result_cache(encoder))
 }
 
+/// Builds the dependency graph.
+///
+/// This function breates the *staging dep-graph*. When the dep-graph is modified by a query
+/// execution, the new dependency information is not kept in memory but directly
+/// output to this file. `save_dep_graph` then finalizes the staging dep-graph
+/// and moves it to the permanent dep-graph path
 pub fn build_dep_graph(
     sess: &Session,
     prev_graph: SerializedDepGraph,

compiler/rustc_incremental/src/persist/work_product.rs

@@ -1,4 +1,6 @@
-//! This module contains files for saving intermediate work-products.
+//! Functions for saving and removing intermediate [work products].
+//!
+//! [work products]: WorkProduct
 
 use crate::persist::fs::*;
 use rustc_fs_util::link_or_copy;
@@ -7,6 +9,7 @@ use rustc_session::Session;
 use std::fs as std_fs;
 use std::path::PathBuf;
 
+/// Copies a CGU work product to the incremental compilation directory, so next compilation can find and reuse it.
 pub fn copy_cgu_workproduct_to_incr_comp_cache_dir(
     sess: &Session,
     cgu_name: &str,
@@ -40,6 +43,7 @@ pub fn copy_cgu_workproduct_to_incr_comp_cache_dir(
     Some((work_product_id, work_product))
 }
 
+/// Removes files for a given work product.
 pub fn delete_workproduct_files(sess: &Session, work_product: &WorkProduct) {
     if let Some(ref file_name) = work_product.saved_file {
         let path = in_incr_comp_dir_sess(sess, file_name);