Merge pull request #895 from rylev/add-docs1

Add some basic docs

Author: rylev

collector/src/lib.rs

@@ -16,24 +16,33 @@ pub use self_profile::{QueryData, SelfProfile};
 #[derive(Debug, Copy, Clone, PartialEq, PartialOrd, Deserialize)]
 pub struct DeltaTime(#[serde(with = "round_float")] pub f64);
 
+/// The bound of a range changes in codebase
+///
+/// This can either be the upper or lower bound
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum Bound {
-    // sha, unverified
+    /// An unverified git commit (in sha form)
     Commit(String),
+    /// A date in time
     Date(NaiveDate),
+    /// No bound
     None,
 }
 
 impl Bound {
+    /// Tests whether self bounds the commit to the left
     pub fn left_match(&self, commit: &Commit) -> bool {
-        let last_month = chrono::Utc::now().date().naive_utc() - chrono::Duration::days(30);
         match self {
             Bound::Commit(sha) => commit.sha == **sha,
             Bound::Date(date) => commit.date.0.naive_utc().date() >= *date,
-            Bound::None => last_month <= commit.date.0.naive_utc().date(),
+            Bound::None => {
+                let last_month = chrono::Utc::now().date().naive_utc() - chrono::Duration::days(30);
+                last_month <= commit.date.0.naive_utc().date()
+            }
         }
     }
 
+    /// Tests whether self bounds the commit to the right
     pub fn right_match(&self, commit: &Commit) -> bool {
         match self {
             Bound::Commit(sha) => commit.sha == **sha,

database/src/lib.rs

@@ -189,13 +189,18 @@ impl Ord for Commit {
     }
 }
 
+/// The compilation profile (i.e., how the crate was built)
 #[derive(
     Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, serde::Serialize, serde::Deserialize,
 )]
 pub enum Profile {
+    /// A checked build (i.e., no codegen)
     Check,
+    /// A debug build (i.e., low optimizations)
     Debug,
+    /// A doc build
     Doc,
+    /// An optimized "release" build
     Opt,
 }
 
@@ -227,15 +232,23 @@ impl fmt::Display for Profile {
     }
 }
 
+/// The incremental cache state
+///
+/// These are usually reported to users in a "flipped" way. For example,
+/// `Cache::Empty` means we're doing a "full" build. We present this to users as "full".
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
 #[serde(tag = "variant", content = "name")]
 pub enum Cache {
+    /// Empty cache (i.e., full build)
     #[serde(rename = "full")]
     Empty,
+    /// Empty cache but still incremental (i.e., a full incremental build)
     #[serde(rename = "incr-full")]
     IncrementalEmpty,
+    /// Cache is fully up-to-date (i.e., nothing has changed)
     #[serde(rename = "incr-unchanged")]
     IncrementalFresh,
+    /// Cache is mostly up-to-date but something has been changed
     #[serde(rename = "incr-patched")]
     IncrementalPatch(PatchName),
 }
@@ -378,9 +391,12 @@ pub enum Label {
     Query(QueryLabel),
 }
 
+/// An identifier for a built version of the compiler
 #[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub enum ArtifactId {
+    /// A built version of the compiler at an exact commit
     Commit(Commit),
+    /// A symbolic tag for a built compiler like "1.51.0"
     Artifact(String),
 }
 
@@ -434,16 +450,26 @@ pub struct LabelId(pub u8, pub u32);
 #[derive(Serialize, Deserialize, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
 pub struct ArtifactIdNumber(pub u32);
 
+/// Id lookups for various things
+///
+/// This is a quick way to find what the database id for something
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct Index {
+    /// Id look for a commit
     commits: Indexed<Commit>,
+    /// Id lookup of the errors for a crate
     artifacts: Indexed<Box<str>>,
-
+    /// Id lookup of the errors for a crate
     errors: Indexed<Crate>,
+    /// Id lookup of a given process stastic profile
     pstats: Indexed<(Crate, Profile, Cache, ProcessStatistic)>,
+    /// Id lookup of a given process query label
     queries: Indexed<(Crate, Profile, Cache, QueryLabel)>,
 }
 
+/// An index lookup
+///
+/// Given a `T` find what its database id is
 #[derive(Debug, Clone, Serialize, Deserialize)]
 struct Indexed<T> {
     #[serde(with = "index_serde")]

site/src/comparison.rs

@@ -237,14 +237,17 @@ pub async fn compare_given_commits(
         Some(b) => b,
         None => return Ok(None),
     };
-    let cids = Arc::new(vec![a.clone().into(), b.clone().into()]);
+    let cids = Arc::new(vec![a.clone(), b.clone()]);
 
+    // get all crates, cache, and profile combinations for the given stat
     let query = selector::Query::new()
         .set::<String>(Tag::Crate, selector::Selector::All)
         .set::<String>(Tag::Cache, selector::Selector::All)
         .set::<String>(Tag::Profile, selector::Selector::All)
         .set(Tag::ProcessStatistic, selector::Selector::One(stat.clone()));
 
+    // `responses` contains a series iterators. The first element in the iterator is the data
+    // for `a` and the second is the data for `b`
     let mut responses = data.query::<Option<f64>>(query, cids).await?;
 
     let conn = data.conn().await;
@@ -257,18 +260,30 @@ pub async fn compare_given_commits(
     }))
 }
 
-/// Data associated with a specific date
+/// Data associated with a specific artifact
 #[derive(Debug, Clone, Serialize)]
 pub struct DateData {
+    /// The artifact in question
+    pub commit: String,
+    /// The date of the artifact if known
     pub date: Option<Date>,
+    /// The pr of the artifact if known
     pub pr: Option<u32>,
-    pub commit: String,
+    /// Benchmark data in the form "$crate-$profile" -> Vec<("$cache", nanoseconds)>
+    ///
+    /// * $profile refers to the flavor of compilation like debug, doc, opt(timized), etc.
+    /// * $cache refers to how much of the compilation must be done and how much is cached
+    /// (e.g., "incr-unchanged" == compiling with full incremental cache and no code having changed)
     pub data: HashMap<String, Vec<(String, f64)>>,
-    // crate -> nanoseconds
+    /// Bootstrap data in the form "$crate" -> nanoseconds
     pub bootstrap: HashMap<String, u64>,
 }
 
 impl DateData {
+    /// For the given `ArtifactId`, consume the first datapoint in each of the given `SeriesResponse`
+    ///
+    /// It is assumed that the provided ArtifactId is the same as artifact id returned as the next data
+    /// point from all of the series `SeriesResponse`s. If this is not true, this function will panic.
     async fn consume_one<'a, T>(
         conn: &dyn database::Connection,
         commit: ArtifactId,

site/src/load.rs

@@ -64,23 +64,32 @@ impl TryCommit {
     }
 }
 
+/// Keys for accessing various services
+///
+/// At the moment only used for accessing GitHub
 #[derive(Debug, Default, Deserialize)]
 pub struct Keys {
+    /// GitHub API token from the `GITHUB_API_TOKEN` env variable
     pub github: Option<String>,
+    /// GitHub webhook secret from the `GITHUB_WEBHOOK_SECRET` env variable
     pub secret: Option<String>,
 }
 
+/// Site configuration
 #[derive(Debug, Deserialize)]
 pub struct Config {
     pub keys: Keys,
 }
 
+/// Site context object that contains global data
 pub struct InputData {
+    /// Site configuration
     pub config: Config,
-
+    /// Cached site landing page
     pub landing_page: ArcSwap<Option<Arc<crate::api::graph::Response>>>,
-
+    /// Index of various common queries
     pub index: ArcSwap<crate::db::Index>,
+    /// Database connection pool
     pub pool: Pool,
 }
 

site/src/selector.rs

@@ -33,22 +33,26 @@ use std::fmt;
 use std::ops::RangeInclusive;
 use std::sync::Arc;
 
-pub fn data_for(data: &Index, is_left: bool, query: Bound) -> Option<ArtifactId> {
+/// Finds the most appropriate `ArtifactId` for a given bound.
+///
+/// Searches the commits in the index either from the left or the right.
+/// If not found in those commits, searches through the artifacts in the index.
+pub fn data_for(data: &Index, is_left: bool, bound: Bound) -> Option<ArtifactId> {
     let commits = data.commits();
     let commit = if is_left {
         commits
             .iter()
-            .find(|commit| query.left_match(commit))
+            .find(|commit| bound.left_match(commit))
             .cloned()
     } else {
         commits
             .iter()
-            .rfind(|commit| query.left_match(commit))
+            .rfind(|commit| bound.left_match(commit))
             .cloned()
     };
     commit.map(|c| ArtifactId::Commit(c)).or_else(|| {
         data.artifacts()
-            .find(|aid| match &query {
+            .find(|aid| match &bound {
                 Bound::Commit(c) => *c == **aid,
                 Bound::Date(_) => false,
                 Bound::None => false,