Add doc comments to new types and public functions

Author: carols10cents

src/version/build_info.rs

@@ -21,7 +21,7 @@ use schema::*;
 #[belongs_to(Version)]
 #[table_name = "build_info"]
 #[primary_key(version_id, rust_version, target)]
-/// Stores information about whether this version built or not on the specified Rust version and
+/// Stores information about whether this version built on the specified Rust version and
 /// target.
 pub struct BuildInfo {
     version_id: i32,
@@ -30,6 +30,9 @@ pub struct BuildInfo {
     pub passed: bool,
 }
 
+/// The columns to select from the `build_info` table. The table also stores `created_at` and
+/// `updated_at` metadata for each row, but we're not displaying those anywhere so we're not
+/// bothering to select them.
 pub const BUILD_INFO_FIELDS: (
     build_info::version_id,
     build_info::rust_version,
@@ -44,13 +47,16 @@ pub const BUILD_INFO_FIELDS: (
 
 #[derive(Debug)]
 /// The maximum version of Rust from each channel that a crate version successfully builds with.
+/// Used for summarizing this information in badge form on crate list pages.
 pub struct MaxBuildInfo {
     pub stable: Option<semver::Version>,
     pub beta: Option<NaiveDate>,
     pub nightly: Option<NaiveDate>,
 }
 
 impl MaxBuildInfo {
+    /// Encode stable semver number as a string and beta and nightly as times appropriate for
+    /// JSON.
     pub fn encode(self) -> EncodableMaxVersionBuildInfo {
         fn naive_date_to_rfc3339(date: NaiveDate) -> String {
             DateTime::<Utc>::from_utc(date.and_hms(0, 0, 0), Utc).to_rfc3339()
@@ -65,6 +71,9 @@ impl MaxBuildInfo {
 }
 
 impl BuildInfo {
+    /// From a set of build information data, Find the largest or latest Rust versions that we know
+    /// about for each channel. Stable uses the largest semver version number; beta and nightly use
+    /// the latest date.
     pub fn max<I>(build_infos: I) -> CargoResult<MaxBuildInfo>
     where
         I: IntoIterator<Item = BuildInfo>,

src/version/mod.rs

@@ -171,6 +171,7 @@ impl Version {
         Ok(())
     }
 
+    /// Orders SemVer numbers so that "higher" version numbers appear first.
     pub fn semantically_newest_first(a: &Self, b: &Self) -> ::std::cmp::Ordering {
         b.num.cmp(&a.num)
     }

src/views/mod.rs

@@ -78,6 +78,7 @@ pub struct EncodableVersionBuildInfo {
 }
 
 #[derive(Debug, Default, Serialize, Deserialize)]
+/// MaxBuildInfo in JSON form.
 pub struct EncodableMaxVersionBuildInfo {
     pub stable: Option<String>,
     pub beta: Option<String>,