diff --git a/src/librustdoc/html/render/search_index.rs b/src/librustdoc/html/render/search_index.rs
index 02e1e0da99ba..497a52977383 100644
--- a/src/librustdoc/html/render/search_index.rs
+++ b/src/librustdoc/html/render/search_index.rs
@@ -239,6 +239,9 @@ fn push(
         self.alias_pointers.push(alias_pointer);
         index
     }
+    /// Add potential search result to the database and return the row ID.
+    ///
+    /// The returned ID can be used to attach more data to the search result.
     fn add_entry(&mut self, name: Symbol, entry_data: EntryData, desc: String) -> usize {
         let fqp = if let Some(module_path_index) = entry_data.module_path {
             let mut fqp = self.path_data[module_path_index].as_ref().unwrap().module_path.clone();
@@ -248,6 +251,11 @@ fn add_entry(&mut self, name: Symbol, entry_data: EntryData, desc: String) -> us
         } else {
             vec![name]
         };
+        // If a path with the same name already exists, but no entry does,
+        // we can fill in the entry without having to allocate a new row ID.
+        //
+        // Because paths and entries both share the same index, using the same
+        // ID saves space by making the tree smaller.
         if let Some(&other_path) = self.crate_paths_index.get(&(entry_data.ty, fqp))
             && self.entry_data[other_path].is_none()
             && self.descs[other_path].is_empty()