generate-copyright: rename some functions to make it clearer.

Also move some types into their own module, and split up the writelines.

Author: jonathanpallant

src/tools/generate-copyright/src/main.rs

@@ -15,34 +15,43 @@ fn main() -> Result<(), Error> {
     let cargo = env_path("CARGO")?;
     let license_metadata = env_path("LICENSE_METADATA")?;
 
-    let metadata: Metadata = serde_json::from_slice(&std::fs::read(&license_metadata)?)?;
+    let collected_tree_metadata: Metadata =
+        serde_json::from_slice(&std::fs::read(&license_metadata)?)?;
 
-    let mut deps_set = BTreeSet::new();
+    let mut collected_cargo_metadata = BTreeSet::new();
 
     let root_path = std::path::absolute(".")?;
     for dep in cargo_metadata::get(&cargo, Path::new("./Cargo.toml"), &root_path)? {
-        deps_set.insert(dep);
+        collected_cargo_metadata.insert(dep);
     }
     for dep in cargo_metadata::get(&cargo, Path::new("./src/tools/cargo/Cargo.toml"), &root_path)? {
-        deps_set.insert(dep);
+        collected_cargo_metadata.insert(dep);
     }
     for dep in cargo_metadata::get(&cargo, Path::new("./library/std/Cargo.toml"), &root_path)? {
-        deps_set.insert(dep);
+        collected_cargo_metadata.insert(dep);
     }
 
     let mut buffer = Vec::new();
 
-    write!(
+    writeln!(buffer, "# In-tree files")?;
+    writeln!(buffer)?;
+    writeln!(
         buffer,
-        "# In-tree files\n\nThe following licenses cover the in-tree source files that were used in this release:\n\n"
+        "The following licenses cover the in-tree source files that were used in this release:"
     )?;
-    render_recursive(&metadata.files, &mut buffer, 0)?;
+    writeln!(buffer)?;
+    render_tree_recursive(&collected_tree_metadata.files, &mut buffer, 0)?;
 
-    write!(
+    writeln!(buffer)?;
+
+    writeln!(buffer, "# Out-of-tree files")?;
+    writeln!(buffer)?;
+    writeln!(
         buffer,
-        "\n# Out-of-tree files\n\nThe following licenses cover the out-of-tree crates that were used in this release:\n\n"
+        "The following licenses cover the out-of-tree crates that were used in this release:"
     )?;
-    render_deps(deps_set.iter(), &mut buffer)?;
+    writeln!(buffer)?;
+    render_deps(collected_cargo_metadata.iter(), &mut buffer)?;
 
     std::fs::write(&dest, &buffer)?;
 
@@ -51,47 +60,51 @@ fn main() -> Result<(), Error> {
 
 /// Recursively draw the tree of files/folders we found on disk and their licences, as
 /// markdown, into the given Vec.
-fn render_recursive(node: &Node, buffer: &mut Vec<u8>, depth: usize) -> Result<(), Error> {
+fn render_tree_recursive(
+    node: &Node,
+    buffer: &mut Vec<u8>,
+    depth: usize,
+) -> Result<(), Error> {
     let prefix = std::iter::repeat("> ").take(depth + 1).collect::<String>();
 
     match node {
         Node::Root { children } => {
             for child in children {
-                render_recursive(child, buffer, depth)?;
+                render_tree_recursive(child, buffer, depth)?;
             }
         }
         Node::Directory { name, children, license } => {
-            render_license(&prefix, std::iter::once(name), license.iter(), buffer)?;
+            render_tree_license(&prefix, std::iter::once(name), license.iter(), buffer)?;
             if !children.is_empty() {
                 writeln!(buffer, "{prefix}")?;
                 writeln!(buffer, "{prefix}*Exceptions:*")?;
                 for child in children {
                     writeln!(buffer, "{prefix}")?;
-                    render_recursive(child, buffer, depth + 1)?;
+                    render_tree_recursive(child, buffer, depth + 1)?;
                 }
             }
         }
         Node::CondensedDirectory { name, licenses } => {
-            render_license(&prefix, std::iter::once(name), licenses.iter(), buffer)?;
+            render_tree_license(&prefix, std::iter::once(name), licenses.iter(), buffer)?;
         }
         Node::Group { files, directories, license } => {
-            render_license(
+            render_tree_license(
                 &prefix,
                 directories.iter().chain(files.iter()),
                 std::iter::once(license),
                 buffer,
             )?;
         }
         Node::File { name, license } => {
-            render_license(&prefix, std::iter::once(name), std::iter::once(license), buffer)?;
+            render_tree_license(&prefix, std::iter::once(name), std::iter::once(license), buffer)?;
         }
     }
 
     Ok(())
 }
 
 /// Draw a series of sibling files/folders, as markdown, into the given Vec.
-fn render_license<'a>(
+fn render_tree_license<'a>(
     prefix: &str,
     names: impl Iterator<Item = &'a String>,
     licenses: impl Iterator<Item = &'a License>,
@@ -143,11 +156,13 @@ fn render_deps<'a, 'b>(
     Ok(())
 }
 
+/// Describes a tree of metadata for our filesystem tree
 #[derive(serde::Deserialize)]
 struct Metadata {
     files: Node,
 }
 
+/// Describes one node in our metadata tree
 #[derive(serde::Deserialize)]
 #[serde(rename_all = "kebab-case", tag = "type")]
 pub(crate) enum Node {
@@ -158,12 +173,14 @@ pub(crate) enum Node {
     Group { files: Vec<String>, directories: Vec<String>, license: License },
 }
 
+/// A License has an SPDX license name and a list of copyright holders.
 #[derive(serde::Deserialize)]
 struct License {
     spdx: String,
     copyright: Vec<String>,
 }
 
+/// Grab an environment variable as a PathBuf, or fail nicely.
 fn env_path(var: &str) -> Result<PathBuf, Error> {
     if let Some(var) = std::env::var_os(var) {
         Ok(var.into())