3 files changed, 34 insertions, 31 deletions
diff --git a/tvix/eval/src/value/attrs.rs b/tvix/eval/src/value/attrs.rs
index d122f9155d2c..fddf0b582ccb 100644
--- a/tvix/eval/src/value/attrs.rs
+++ b/tvix/eval/src/value/attrs.rs
@@ -150,7 +150,8 @@ impl PartialEq for NixAttrs {
 }
 
 impl NixAttrs {
-    // Update one attribute set with the values of the other.
+    /// Return an attribute set containing the merge of the two
+    /// provided sets. Keys from the `other` set have precedence.
     pub fn update(self, other: Self) -> Self {
         // Short-circuit on some optimal cases:
         match (&self.0, &other.0) {
@@ -301,17 +302,19 @@ impl NixAttrs {
     }
 }
 
-// In Nix, name/value attribute pairs are frequently constructed from
-// literals. This particular case should avoid allocation of a map,
-// additional heap values etc. and use the optimised `KV` variant
-// instead.
-//
-// `slice` is the top of the stack from which the attrset is being
-// constructed, e.g.
-//
-//   slice: [ "value" 5 "name" "foo" ]
-//   index:   0       1 2      3
-//   stack:   3       2 1      0
+/// In Nix, name/value attribute pairs are frequently constructed from
+/// literals. This particular case should avoid allocation of a map,
+/// additional heap values etc. and use the optimised `KV` variant
+/// instead.
+///
+/// ```norust
+/// `slice` is the top of the stack from which the attrset is being
+/// constructed, e.g.
+///
+///   slice: [ "value" 5 "name" "foo" ]
+///   index:   0       1 2      3
+///   stack:   3       2 1      0
+/// ```
 fn attempt_optimise_kv(slice: &mut [Value]) -> Option<NixAttrs> {
     let (name_idx, value_idx) = {
         match (&slice[2], &slice[0]) {
@@ -340,8 +343,8 @@ fn attempt_optimise_kv(slice: &mut [Value]) -> Option<NixAttrs> {
     }))
 }
 
-// Set an attribute on an in-construction attribute set, while
-// checking against duplicate keys.
+/// Set an attribute on an in-construction attribute set, while
+/// checking against duplicate keys.
 fn set_attr(attrs: &mut NixAttrs, key: NixString, value: Value) -> Result<(), ErrorKind> {
     match attrs.0.map_mut().entry(key) {
         btree_map::Entry::Occupied(entry) => Err(ErrorKind::DuplicateAttrsKey {
@@ -355,12 +358,12 @@ fn set_attr(attrs: &mut NixAttrs, key: NixString, value: Value) -> Result<(), Er
     }
 }
 
-// Set a nested attribute inside of an attribute set, throwing a
-// duplicate key error if a non-hashmap entry already exists on the
-// path.
-//
-// There is some optimisation potential for this simple implementation
-// if it becomes a problem.
+/// Set a nested attribute inside of an attribute set, throwing a
+/// duplicate key error if a non-hashmap entry already exists on the
+/// path.
+///
+/// There is some optimisation potential for this simple implementation
+/// if it becomes a problem.
 fn set_nested_attr(
     attrs: &mut NixAttrs,
     key: NixString,
diff --git a/tvix/eval/src/value/builtin.rs b/tvix/eval/src/value/builtin.rs
index 7572103ec96e..5d39a0a9f557 100644
--- a/tvix/eval/src/value/builtin.rs
+++ b/tvix/eval/src/value/builtin.rs
@@ -39,7 +39,7 @@ pub struct Builtin {
     arity: usize,
     func: BuiltinFn,
 
-    // Partially applied function arguments.
+    /// Partially applied function arguments.
     partials: Vec<Value>,
 }
 
diff --git a/tvix/eval/src/value/string.rs b/tvix/eval/src/value/string.rs
index 095f87645cc5..aa542181f9b1 100644
--- a/tvix/eval/src/value/string.rs
+++ b/tvix/eval/src/value/string.rs
@@ -72,12 +72,12 @@ impl NixString {
         }
     }
 
-    // Return a displayable representation of the string as an
-    // identifier.
-    //
-    // This is used when printing out strings used as e.g. attribute
-    // set keys, as those are only escaped in the presence of special
-    // characters.
+    /// Return a displayable representation of the string as an
+    /// identifier.
+    ///
+    /// This is used when printing out strings used as e.g. attribute
+    /// set keys, as those are only escaped in the presence of special
+    /// characters.
     pub fn ident_str(&self) -> Cow<str> {
         let escaped = nix_escape_string(self.as_str());
 
@@ -111,10 +111,10 @@ fn nix_escape_char(ch: char, next: Option<&char>) -> Option<&'static str> {
     }
 }
 
-// Escape a Nix string for display, as most user-visible representation
-// are escaped strings.
-//
-// Note that this does not add the outer pair of surrounding quotes.
+/// Escape a Nix string for display, as most user-visible representation
+/// are escaped strings.
+///
+/// Note that this does not add the outer pair of surrounding quotes.
 fn nix_escape_string(input: &str) -> Cow<str> {
     let mut iter = input.chars().enumerate().peekable();