Clarify data_for function

Author: rylev

collector/src/lib.rs

@@ -16,12 +16,15 @@ 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
+/// The bound for finding an artifact
 ///
-/// This can either be the upper or lower bound
+/// This can either be the upper or lower bound.
+/// In the case of commits or tags this is an exact bound, but for dates
+/// it's a best effort (i.e., if the bound is a date but there are no artifacts
+/// for that date, we'll find the artifact that most closely matches).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum Bound {
-    /// An unverified git commit (in sha form)
+    /// An unverified git commit (in sha form) or a tag of a commit (e.g., "1.53.0")
     Commit(String),
     /// A date in time
     Date(NaiveDate),
@@ -30,7 +33,7 @@ pub enum Bound {
 }
 
 impl Bound {
-    /// Tests whether self bounds the commit to the left
+    /// Tests whether `self` matches commit when searching from the left
     pub fn left_match(&self, commit: &Commit) -> bool {
         match self {
             Bound::Commit(sha) => commit.sha == **sha,
@@ -42,7 +45,7 @@ impl Bound {
         }
     }
 
-    /// Tests whether self bounds the commit to the right
+    /// Tests whether `self` matches commit when searching from the right
     pub fn right_match(&self, commit: &Commit) -> bool {
         match self {
             Bound::Commit(sha) => commit.sha == **sha,

database/src/lib.rs

@@ -450,9 +450,11 @@ 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
+/// Cached Id lookups for many database tables.
 ///
-/// This is a quick way to find what the database id for something
+/// This is a quick way to find what the database id for something.
+/// Essentially duplicates of the various database tables (artifacts,
+/// error_series, pstat_series, etc.) so that we can avoid a network round-trip.
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct Index {
     /// Id look for a commit

site/src/comparison.rs

@@ -230,9 +230,9 @@ pub async fn compare_given_commits(
     master_commits: &[collector::MasterCommit],
 ) -> Result<Option<Comparison>, BoxedError> {
     let a = ctxt
-        .data_for(true, start.clone())
+        .artifact_id_for_bound(start.clone(), true)
         .ok_or(format!("could not find start commit for bound {:?}", start))?;
-    let b = match ctxt.data_for(false, end.clone()) {
+    let b = match ctxt.artifact_id_for_bound(end.clone(), false) {
         Some(b) => b,
         None => return Ok(None),
     };

site/src/load.rs

@@ -95,8 +95,8 @@ impl SiteCtxt {
         ]
     }
 
-    pub fn data_for(&self, is_left: bool, query: Bound) -> Option<ArtifactId> {
-        crate::selector::data_for(&self.index.load(), is_left, query)
+    pub fn artifact_id_for_bound(&self, query: Bound, is_left: bool) -> Option<ArtifactId> {
+        crate::selector::artifact_id_for_bound(&self.index.load(), query, is_left)
     }
 
     pub fn data_range(&self, range: RangeInclusive<Bound>) -> Vec<Commit> {

site/src/selector.rs

@@ -39,7 +39,7 @@ use std::sync::Arc;
 ///
 /// 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> {
+pub fn artifact_id_for_bound(data: &Index, bound: Bound, is_left: bool) -> Option<ArtifactId> {
     let commits = data.commits();
     let commit = if is_left {
         commits