offset_template -> sorted_template

EtomicBomb · EtomicBomb · commit 46abe8a627b5 · 2024-06-28T16:24:35.000Z
diff --git a/src/librustdoc/config.rs b/src/librustdoc/config.rs
@@ -749,7 +749,7 @@ impl Options {
         let extern_html_root_takes_precedence =
             matches.opt_present("extern-html-root-takes-precedence");
         let html_no_source = matches.opt_present("html-no-source");
-        let MergeResult { read_rendered_cci, write_rendered_cci } = match parse_merge(matches) {
+        let ShouldMerge { read_rendered_cci, write_rendered_cci } = match parse_merge(matches) {
             Ok(result) => result,
             Err(e) => dcx.fatal(format!("could not parse --merge: {e}")),
         };
@@ -939,20 +939,23 @@ impl PathToParts {
     }
 }
 
-struct MergeResult {
+/// Controls merging of cross-crate information
+struct ShouldMerge {
+    /// Should we append to existing cci in the doc root
     read_rendered_cci: bool,
+    /// Should we write cci to the doc root
     write_rendered_cci: bool,
 }
 
 /// Extracts read_rendered_cci and write_rendered_cci from command line arguments, or
 /// reports an error.
-fn parse_merge(matches: &getopts::Matches) -> Result<MergeResult, &'static str> {
+fn parse_merge(matches: &getopts::Matches) -> Result<ShouldMerge, &'static str> {
     match matches.opt_str("merge").as_deref() {
         // default = auto
-        None => Ok(MergeResult { read_rendered_cci: true, write_rendered_cci: true }),
-        Some("auto") => Ok(MergeResult { read_rendered_cci: true, write_rendered_cci: true }),
-        Some("none") => Ok(MergeResult { read_rendered_cci: false, write_rendered_cci: false }),
-        Some("write-only") => Ok(MergeResult { read_rendered_cci: false, write_rendered_cci: true }),
+        None => Ok(ShouldMerge { read_rendered_cci: true, write_rendered_cci: true }),
+        Some("auto") => Ok(ShouldMerge { read_rendered_cci: true, write_rendered_cci: true }),
+        Some("none") => Ok(ShouldMerge { read_rendered_cci: false, write_rendered_cci: false }),
+        Some("write-only") => Ok(ShouldMerge { read_rendered_cci: false, write_rendered_cci: true }),
         Some(_) => Err("argument to --merge must be `auto`, `none`, or `write-only`"),
     }
 }
diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs
@@ -35,7 +35,7 @@ mod span_map;
 mod type_layout;
 mod write_shared;
 mod sorted_json;
-mod offset_template;
+mod sorted_template;
 
 pub(crate) use self::context::*;
 pub(crate) use self::span_map::{collect_spans_and_sources, LinkFromSrc};
diff --git a/src/librustdoc/html/render/sorted_template.rs b/src/librustdoc/html/render/sorted_template.rs
@@ -1,6 +1,6 @@
 use std::fmt;
 use std::marker::PhantomData;
-use rustc_data_structures::fx::FxHashSet;
+use std::collections::BTreeSet;
 use std::str::FromStr;
 
 use serde::{Serialize, Deserialize};
@@ -9,20 +9,23 @@ use serde::{Serialize, Deserialize};
 ///
 /// Last line of the rendered output is a comment encoding the next insertion point.
 #[derive(Debug, Clone)]
-pub(crate) struct OffsetTemplate<F> {
+pub(crate) struct SortedTemplate<F> {
     format: PhantomData<F>,
     before: String,
     after: String,
-    contents: FxHashSet<String>,
+    contents: BTreeSet<String>,
 }
 
+/// Written to last line of file to specify the location of each fragment
 #[derive(Serialize, Deserialize, Debug, Clone)]
 struct Offset {
+    /// Index of the first byte in the template
     start: usize,
+    /// The length of each fragment in the encoded template, including the separator
     delta: Vec<usize>,
 }
 
-impl<F> OffsetTemplate<F> {
+impl<F> SortedTemplate<F> {
     /// Generate this template from arbitary text.
     /// Will insert wherever the substring `magic` can be found.
     /// Errors if it does not appear exactly once.
@@ -40,23 +43,22 @@ impl<F> OffsetTemplate<F> {
     pub(crate) fn before_after<S: ToString, T: ToString>(before: S, after: T) -> Self {
         let before = before.to_string();
         let after = after.to_string();
-        OffsetTemplate { format: PhantomData, before, after, contents: Default::default() }
+        SortedTemplate { format: PhantomData, before, after, contents: Default::default() }
     }
 }
 
-impl<F: FileFormat> OffsetTemplate<F> {
-    /// Adds this text to the next insert point
+impl<F: FileFormat> SortedTemplate<F> {
+    /// Adds this text to the template
     pub(crate) fn append(&mut self, insert: String) {
         self.contents.insert(insert);
     }
 }
 
-impl<F: FileFormat> fmt::Display for OffsetTemplate<F> {
+impl<F: FileFormat> fmt::Display for SortedTemplate<F> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         let mut delta = Vec::default();
         write!(f, "{}", self.before)?;
-        let mut contents: Vec<_> = self.contents.iter().collect();
-        contents.sort_unstable();
+        let contents: Vec<_> = self.contents.iter().collect();
         let mut sep = "";
         for content in contents {
             delta.push(sep.len() + content.len());
@@ -74,28 +76,28 @@ fn checked_split_at(s: &str, index: usize) -> Option<(&str, &str)> {
     s.is_char_boundary(index).then(|| s.split_at(index))
 }
 
-impl<F: FileFormat> FromStr for OffsetTemplate<F> {
+impl<F: FileFormat> FromStr for SortedTemplate<F> {
     type Err = Error;
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         let (s, offset) = s.rsplit_once("\n").ok_or(Error)?;
         let offset = offset.strip_prefix(F::COMMENT_START).ok_or(Error)?;
         let offset = offset.strip_suffix(F::COMMENT_END).ok_or(Error)?;
         let offset: Offset = serde_json::from_str(&offset).map_err(|_| Error)?;
         let (before, mut s) = checked_split_at(s, offset.start).ok_or(Error)?;
-        let mut contents = Vec::default();
+        let mut contents = BTreeSet::default();
         let mut sep = "";
         for &index in offset.delta.iter() {
             let (content, rest) = checked_split_at(s, index).ok_or(Error)?;
             s = rest;
             let content = content.strip_prefix(sep).ok_or(Error)?;
-            contents.push(content);
+            contents.insert(content.to_string());
             sep = F::SEPARATOR;
         }
-        Ok(OffsetTemplate {
+        Ok(SortedTemplate {
             format: PhantomData,
             before: before.to_string(),
             after: s.to_string(),
-            contents: contents.into_iter().map(ToString::to_string).collect(),
+            contents,
         })
     }
 }
@@ -142,21 +144,21 @@ mod tests {
         s.starts_with("//")
     }
 
-    /// not correct, but good enough for these tests
     fn is_comment_html(s: &str) -> bool {
+        // not correct but good enough for these tests
         s.starts_with("<!--") && s.ends_with("-->")
     }
 
     #[test]
     fn html_from_empty() {
-        let inserts = ["<p>hello</p>", "<p>kind</p>", "<p>world</p>"];
-        let mut template = OffsetTemplate::<Html>::before_after("", "");
+        let inserts = ["<p>hello</p>", "<p>kind</p>", "<p>hello</p>", "<p>world</p>"];
+        let mut template = SortedTemplate::<Html>::before_after("", "");
         for insert in inserts {
             template.append(insert.to_string());
         }
         let template = format!("{template}");
         let (template, end) = template.rsplit_once("\n").unwrap();
-        assert_eq!(template, inserts.join(""));
+        assert_eq!(template, "<p>hello</p><p>kind</p><p>world</p>");
         assert!(is_comment_html(end));
         assert!(!end.contains("\n"));
     }
@@ -166,7 +168,7 @@ mod tests {
         let inserts = ["<p>hello</p>", "<p>kind</p>", "<p>world</p>"];
         let before = "<html><head></head><body>";
         let after = "</body>";
-        let mut template = OffsetTemplate::<Html>::before_after(before, after);
+        let mut template = SortedTemplate::<Html>::before_after(before, after);
         for insert in inserts {
             template.append(insert.to_string());
         }
@@ -179,21 +181,21 @@ mod tests {
 
     #[test]
     fn js_from_empty() {
-        let inserts = ["1", "2", "3"];
-        let mut template = OffsetTemplate::<Js>::before_after("", "");
+        let inserts = ["1", "2", "2", "2", "3", "1"];
+        let mut template = SortedTemplate::<Js>::before_after("", "");
         for insert in inserts {
             template.append(insert.to_string());
         }
         let template = format!("{template}");
         let (template, end) = template.rsplit_once("\n").unwrap();
-        assert_eq!(template, inserts.join(","));
+        assert_eq!(template, "1,2,3");
         assert!(is_comment_js(end));
         assert!(!end.contains("\n"));
     }
 
     #[test]
     fn js_empty_array() {
-        let template = OffsetTemplate::<Js>::before_after("[", "]");
+        let template = SortedTemplate::<Js>::before_after("[", "]");
         let template = format!("{template}");
         let (template, end) = template.rsplit_once("\n").unwrap();
         assert_eq!(template, format!("[]"));
@@ -204,7 +206,7 @@ mod tests {
     #[test]
     fn js_number_array() {
         let inserts = ["1", "2", "3"];
-        let mut template = OffsetTemplate::<Js>::before_after("[", "]");
+        let mut template = SortedTemplate::<Js>::before_after("[", "]");
         for insert in inserts {
             template.append(insert.to_string());
         }
@@ -217,8 +219,8 @@ mod tests {
 
     #[test]
     fn magic_js_number_array() {
-        let inserts = ["1"];
-        let mut template = OffsetTemplate::<Js>::magic("[#]", "#").unwrap();
+        let inserts = ["1", "1"];
+        let mut template = SortedTemplate::<Js>::magic("[#]", "#").unwrap();
         for insert in inserts {
             template.append(insert.to_string());
         }
@@ -232,12 +234,12 @@ mod tests {
     #[test]
     fn round_trip_js() {
         let inserts = ["1", "2", "3"];
-        let mut template = OffsetTemplate::<Js>::before_after("[", "]");
+        let mut template = SortedTemplate::<Js>::before_after("[", "]");
         for insert in inserts {
             template.append(insert.to_string());
         }
         let template1 = format!("{template}");
-        let mut template = OffsetTemplate::<Js>::from_str(&template1).unwrap();
+        let mut template = SortedTemplate::<Js>::from_str(&template1).unwrap();
         assert_eq!(template1, format!("{template}"));
         template.append("4".to_string());
         let template = format!("{template}");
@@ -248,34 +250,34 @@ mod tests {
 
     #[test]
     fn round_trip_html() {
-        let inserts = ["<p>hello</p>", "<p>kind</p>", "<p>world</p>"];
+        let inserts = ["<p>hello</p>", "<p>kind</p>", "<p>world</p>", "<p>kind</p>"];
         let before = "<html><head></head><body>";
         let after = "</body>";
-        let mut template = OffsetTemplate::<Html>::before_after(before, after);
+        let mut template = SortedTemplate::<Html>::before_after(before, after);
         template.append(inserts[0].to_string());
         template.append(inserts[1].to_string());
         let template = format!("{template}");
-        let mut template = OffsetTemplate::<Html>::from_str(&template).unwrap();
+        let mut template = SortedTemplate::<Html>::from_str(&template).unwrap();
         template.append(inserts[2].to_string());
         let template = format!("{template}");
         let (template, end) = template.rsplit_once("\n").unwrap();
-        assert_eq!(template, format!("{before}{}{after}", inserts.join("")));
+        assert_eq!(template, format!("{before}<p>hello</p><p>kind</p><p>world</p>{after}"));
         assert!(is_comment_html(end));
     }
 
     #[test]
     fn blank_js() {
         let inserts = ["1", "2", "3"];
-        let mut template = OffsetTemplate::<Js>::before_after("", "");
+        let template = SortedTemplate::<Js>::before_after("", "");
         let template = format!("{template}");
         let (t, _) = template.rsplit_once("\n").unwrap();
         assert_eq!(t, "");
-        let mut template = OffsetTemplate::<Js>::from_str(&template).unwrap();
+        let mut template = SortedTemplate::<Js>::from_str(&template).unwrap();
         for insert in inserts {
             template.append(insert.to_string());
         }
         let template1 = format!("{template}");
-        let mut template = OffsetTemplate::<Js>::from_str(&template1).unwrap();
+        let mut template = SortedTemplate::<Js>::from_str(&template1).unwrap();
         assert_eq!(template1, format!("{template}"));
         template.append("4".to_string());
         let template = format!("{template}");
diff --git a/src/librustdoc/html/render/write_shared.rs b/src/librustdoc/html/render/write_shared.rs
