diff --git a/src/models/krate.rs b/src/models/krate.rs
index c6fcfb6e6f8..1459a76a7fb 100644
--- a/src/models/krate.rs
+++ b/src/models/krate.rs
@@ -331,7 +331,8 @@ impl Crate {
     }
 
     /// Return both the newest (most recently updated) and
-    /// highest version (in semver order) for the current crate.
+    /// highest version (in semver order) for the current crate,
+    /// where all top versions are not yanked.
     pub fn top_versions(&self, conn: &mut impl Conn) -> QueryResult<TopVersions> {
         Ok(TopVersions::from_date_version_pairs(
             self.versions()
@@ -475,10 +476,12 @@ impl From<BoxedAppError> for OwnerAddError {
 }
 
 pub trait CrateVersions {
+    /// Return all non-yanked versions of a crate.
     fn versions(&self) -> versions::BoxedQuery<'_, Pg> {
         self.all_versions().filter(versions::yanked.eq(false))
     }
 
+    /// Return all versions of a crate, including yanked ones.
     fn all_versions(&self) -> versions::BoxedQuery<'_, Pg>;
 }
 
diff --git a/src/models/version.rs b/src/models/version.rs
index 958d331a9ee..cdd612c0a13 100644
--- a/src/models/version.rs
+++ b/src/models/version.rs
@@ -126,6 +126,8 @@ fn strip_build_metadata(version: &str) -> &str {
 
 /// The highest version (semver order) and the most recently updated version.
 /// Typically used for a single crate.
+/// Note: `TopVersion` itself does not guarantee whether versions are yanked or not,
+/// this must be guaranteed by the input versions.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct TopVersions {
     /// The "highest" version in terms of semver