Add some comments

crates/uv-scripts/Cargo.toml

@@ -15,8 +15,8 @@ uv-settings = { workspace = true }
 uv-workspace = { workspace = true }
 
 fs-err = { workspace = true, features = ["tokio"] }
+indoc = { workspace = true }
 memchr = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
 thiserror = { workspace = true }
 toml = { workspace = true }
-indoc = { workspace = true }

crates/uv-scripts/src/lib.rs

@@ -90,21 +90,19 @@ impl Pep723Script {
     }
 
     /// Replace the existing metadata in the file with new metadata and write the updated content.
-    pub async fn replace_metadata(&self, new_metadata: &str) -> Result<(), Pep723Error> {
-        let new_content = format!(
+    pub async fn write(&self, metadata: &str) -> Result<(), Pep723Error> {
+        let content = format!(
             "{}{}{}",
             if self.prelude.is_empty() {
                 String::new()
             } else {
                 format!("{}\n", self.prelude)
             },
-            serialize_metadata(new_metadata),
+            serialize_metadata(metadata),
             self.raw
         );
 
-        fs_err::tokio::write(&self.path, new_content)
-            .await
-            .map_err(std::convert::Into::into)
+        Ok(fs_err::tokio::write(&self.path, content).await?)
     }
 }
 

crates/uv-workspace/src/pyproject_mut.rs

@@ -51,7 +51,9 @@ pub enum ArrayEdit {
 /// Specifies whether dependencies are added to a script file or a `pyproject.toml` file.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 pub enum DependencyTarget {
+    /// A PEP 723 script, with inline metadata.
     Script,
+    /// A project with a `pyproject.toml`.
     PyProjectToml,
 }
 
@@ -92,7 +94,8 @@ impl PyProjectTomlMut {
         Ok(())
     }
 
-    /// Retrieves a mutable reference to the root `Table` of the TOML document, creating the `project` table if necessary.
+    /// Retrieves a mutable reference to the root [`Table`] of the TOML document, creating the
+    /// `project` table if necessary.
     fn doc(&mut self) -> Result<&mut Table, Error> {
         let doc = match self.target {
             DependencyTarget::Script => self.doc.as_table_mut(),
@@ -106,7 +109,8 @@ impl PyProjectTomlMut {
         Ok(doc)
     }
 
-    /// Retrieves an optional mutable reference to the `project` `Table`, returning `None` if it doesn't exist.
+    /// Retrieves an optional mutable reference to the `project` [`Table`], returning `None` if it
+    /// doesn't exist.
     fn doc_mut(&mut self) -> Result<Option<&mut Table>, Error> {
         let doc = match self.target {
             DependencyTarget::Script => Some(self.doc.as_table_mut()),

crates/uv/src/commands/project/add.rs

@@ -357,7 +357,7 @@ pub(crate) async fn add(
                 debug!("No changes to dependencies; skipping update");
                 false
             } else {
-                script.replace_metadata(&content).await?;
+                script.write(&content).await?;
                 true
             }
         }
@@ -372,17 +372,18 @@ pub(crate) async fn add(
             }
         }
     };
-    // If `--frozen`, exit early. There's no reason to lock and sync, and we don't need a `uv.lock`
-    // to exist at all.
-    if frozen {
-        return Ok(ExitStatus::Success);
-    }
 
     // If `--script`, exit early. There's no reason to lock and sync.
     let Target::Project(project, venv) = target else {
         return Ok(ExitStatus::Success);
     };
 
+    // If `--frozen`, exit early. There's no reason to lock and sync, and we don't need a `uv.lock`
+    // to exist at all.
+    if frozen {
+        return Ok(ExitStatus::Success);
+    }
+
     let existing = project.pyproject_toml();
 
     // Update the `pypackage.toml` in-memory.

crates/uv/src/commands/project/remove.rs

@@ -127,7 +127,7 @@ pub(crate) async fn remove(
     // Save the modified dependencies.
     match &target {
         Target::Script(script) => {
-            script.replace_metadata(&toml.to_string()).await?;
+            script.write(&toml.to_string()).await?;
         }
         Target::Project(project) => {
             let pyproject_path = project.root().join("pyproject.toml");