version number, copy_dir_all

Author: EtomicBomb

src/librustdoc/html/render/copy_dir.rs

@@ -4,12 +4,14 @@ use std::fs;
 
 /// Recursively copies the contents of the directory `src` to the directory `dst`.
 /// Analogous to `cp -rf src/* dst` and Python's `shutil.copytree`
+///
+/// Creates all directories needed to perform the copy.
 pub(crate) fn copy_dir_all<S: Into<PathBuf>, D: Into<PathBuf>>(src: S, dst: D) -> Result<()> {
-    copy_dir_mono(src.into(), dst.into())
+    copy_dir_all_mono(src.into(), dst.into())
 }
 
 /// Helper for `copy_dir`
-fn copy_dir_mono(src: PathBuf, dst: PathBuf) -> Result<()> {
+fn copy_dir_all_mono(src: PathBuf, dst: PathBuf) -> Result<()> {
     let mut dirs: Vec<(PathBuf, PathBuf)> = Vec::default();
 
     if !src.is_dir() {

src/librustdoc/html/render/search_index.rs

@@ -429,6 +429,7 @@ pub(crate) fn build_index<'tcx>(
         })
         .collect::<Vec<_>>();
 
+    // XXX: update CrateInfoVersion in write_shared upon any changes to this format.
     struct CrateData<'a> {
         items: Vec<&'a IndexItem>,
         paths: Vec<(ItemType, Vec<Symbol>, Option<Vec<Symbol>>)>,
@@ -682,6 +683,8 @@ pub(crate) fn build_index<'tcx>(
         desc.iter().map(|(len, _)| *len).sum::<usize>() + empty_desc.len()
     );
 
+    // XXX: update CrateInfoVersion in write_shared upon any changes to this format.
+
     // The index, which is actually used to search, is JSON
     // It uses `JSON.parse(..)` to actually load, since JSON
     // parses faster than the full JavaScript syntax.

src/librustdoc/html/render/sorted_json.rs

@@ -15,44 +15,26 @@ use itertools::Itertools as _;
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
 #[serde(from = "Value")]
 #[serde(into = "Value")]
-pub struct SortedJson(String);
+pub(crate) struct SortedJson(String);
 
 impl SortedJson {
     /// If you pass in an array, it will not be sorted.
-    pub fn serialize<T: Serialize>(item: T) -> Self {
+    pub(crate) fn serialize<T: Serialize>(item: T) -> Self {
         SortedJson(serde_json::to_string(&item).unwrap())
     }
 
-    /// Assumes that `item` is already JSON encoded
-    ///
-    /// TODO: remove this, and use SortedJson everywhere JSON is rendered
-    pub fn preserialized(item: String) -> Self {
-        SortedJson(item)
-    }
-
     /// Serializes and sorts
-    pub fn array<T: Borrow<SortedJson>, I: IntoIterator<Item=T>>(items: I) -> Self {
+    pub(crate) fn array<T: Borrow<SortedJson>, I: IntoIterator<Item=T>>(items: I) -> Self {
         let items = items.into_iter()
             .sorted_unstable_by(|a, b| a.borrow().cmp(&b.borrow()))
             .format_with(",", |item, f| f(item.borrow()));
         SortedJson(format!("[{}]", items))
     }
 
-    pub fn array_unsorted<T: Borrow<SortedJson>, I: IntoIterator<Item=T>>(items: I) -> Self {
+    pub(crate) fn array_unsorted<T: Borrow<SortedJson>, I: IntoIterator<Item=T>>(items: I) -> Self {
         let items = items.into_iter().format_with(",", |item, f| f(item.borrow()));
         SortedJson(format!("[{items}]"))
     }
-
-    pub fn object<K, V, I>(items: I) -> Self
-        where K: Borrow<SortedJson>,
-              V: Borrow<SortedJson>,
-              I: IntoIterator<Item=(K, V)>,
-    {
-        let items = items.into_iter()
-            .sorted_unstable_by(|a, b| a.0.borrow().cmp(&b.0.borrow()))
-            .format_with(",", |(k, v), f| f(&format_args!("{}:{}", k.borrow(), v.borrow())));
-        SortedJson(format!("{{{}}}", items))
-    }
 }
 
 impl fmt::Display for SortedJson {
@@ -80,8 +62,16 @@ mod tests {
     fn check(json: SortedJson, serialized: &str) {
         assert_eq!(json.to_string(), serialized);
         assert_eq!(serde_json::to_string(&json).unwrap(), serialized);
+
         let json = json.to_string();
         let json: SortedJson = serde_json::from_str(&json).unwrap();
+
+        assert_eq!(json.to_string(), serialized);
+        assert_eq!(serde_json::to_string(&json).unwrap(), serialized);
+
+        let json = serde_json::to_string(&json).unwrap();
+        let json: SortedJson = serde_json::from_str(&json).unwrap();
+
         assert_eq!(json.to_string(), serialized);
         assert_eq!(serde_json::to_string(&json).unwrap(), serialized);
     }
@@ -100,6 +90,13 @@ mod tests {
         check(json, serialized);
     }
 
+    #[test]
+    fn string() {
+        let json = SortedJson::serialize("he\"llo");
+        let serialized = r#""he\"llo""#;
+        check(json, serialized);
+    }
+
     #[test]
     fn serialize_array() {
         let json = SortedJson::serialize([3, 1, 2]);
@@ -116,6 +113,17 @@ mod tests {
         check(json, serialized);
     }
 
+    #[test]
+    fn nested_array() {
+        let a = SortedJson::serialize(3);
+        let b = SortedJson::serialize(2);
+        let c = SortedJson::serialize(1);
+        let d = SortedJson::serialize([1, 3, 2]);
+        let json = SortedJson::array([a, b, c, d]);
+        let serialized = r#"[1,2,3,[1,3,2]]"#;
+        check(json, serialized);
+    }
+
     #[test]
     fn array_unsorted() {
         let items = ["c", "a", "b"];
@@ -124,15 +132,4 @@ mod tests {
         let json = SortedJson::array_unsorted(items);
         check(json, serialized);
     }
-
-    #[test]
-    fn object() {
-        let items = [("c", 1), ("a", 10), ("b", 3)];
-        let serialized = r#"{"a":10,"b":3,"c":1}"#;
-        let items: Vec<(SortedJson, SortedJson)> = items.into_iter()
-            .map(|(k, v)| (SortedJson::serialize(k), SortedJson::serialize(v)))
-            .collect();
-        let json = SortedJson::object(items);
-        check(json, serialized);
-    }
 }

src/librustdoc/html/render/write_shared.rs

@@ -81,6 +81,7 @@ pub(crate) fn write_shared(
     let crate_name_json = SortedJson::serialize(crate_name); // "rand"
     let external_crates = hack_get_external_crate_names(cx)?;
     let info = CrateInfo {
+        version: CrateInfoVersion::V1,
         src_files_js: PartsAndLocations::<SourcesPart>::get(cx, &crate_name_json)?,
         search_index_js: PartsAndLocations::<SearchIndexPart>::get(cx, index)?,
         all_crates: PartsAndLocations::<AllCratesPart>::get(crate_name_json.clone())?,
@@ -193,9 +194,11 @@ fn write_search_desc(cx: &mut Context<'_>, krate: &Crate, search_desc: &[(usize,
     Ok(())
 }
 
+
 /// Written to `crate-info.json`. Contains pre-rendered contents to insert into the CCI template
 #[derive(Serialize, Deserialize, Clone, Debug)]
 struct CrateInfo {
+    version: CrateInfoVersion,
     src_files_js: PartsAndLocations<SourcesPart>,
     search_index_js: PartsAndLocations<SearchIndexPart>,
     all_crates: PartsAndLocations<AllCratesPart>,
@@ -215,7 +218,7 @@ impl CrateInfo {
             .or_else(|| (&self.type_impl as &dyn Any).downcast_ref())
     }
 
-    /// read all of the crate info from its location on the filesystem
+    /// Read all of the crate info from its location on the filesystem
     fn read(parts_paths: &[PathToParts]) -> Result<Vec<Self>, Error> {
         parts_paths.iter()
             .map(|parts_path| {
@@ -228,6 +231,15 @@ impl CrateInfo {
     }
 }
 
+/// Version for the format of the crate-info.json file.
+///
+/// This enum should only ever have one variant, representing the current version.
+/// Gives pretty good error message about expecting the current version on deserialize.
+///
+/// Must be incremented (V2, V3, etc.) upon any changes to the search index or CrateInfo.
+#[derive(Serialize, Deserialize, Clone, Debug)]
+enum CrateInfoVersion { V1 }
+
 /// Paths (relative to the doc root) and their pre-merge contents
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(transparent)]
@@ -324,7 +336,7 @@ fn hack_get_external_crate_names(cx: &Context<'_>) -> Result<Vec<String>, Error>
         return Ok(Vec::default());
     };
     // this is only run once so it's fine not to cache it
-    // dot_matches_new_line false: all crates on same line. greedy: match last bracket
+    // !dot_matches_new_line: all crates on same line. greedy: match last bracket
     let regex = Regex::new(r"\[.*\]").unwrap();
     let Some(content) = regex.find(&content) else {
         return Err(Error::new("could not find crates list in crates.js", path));