From 06909f182151cf2332a14909e8b772ab4648854e Mon Sep 17 00:00:00 2001
From: Vincent Ambo <mail@tazj.in>
Date: Mon, 5 Sep 2022 01:30:58 +0300
Subject: fix(tvix/eval): fix doc comment syntax where applicable

As pointed out by grfn on cl/6091

Change-Id: I28308577b7cf99dffb4a4fd3cc8783eb9ab4d0d6
Reviewed-on: https://cl.tvl.fyi/c/depot/+/6460
Tested-by: BuildkiteCI
Reviewed-by: sterni <sternenseemann@systemli.org>
---
 tvix/eval/src/value/attrs.rs   | 43 ++++++++++++++++++++++--------------------
 tvix/eval/src/value/builtin.rs |  2 +-
 tvix/eval/src/value/string.rs  | 20 ++++++++++----------
 3 files changed, 34 insertions(+), 31 deletions(-)

(limited to 'tvix/eval/src/value')

diff --git a/tvix/eval/src/value/attrs.rs b/tvix/eval/src/value/attrs.rs
index d122f9155d..fddf0b582c 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 7572103ec9..5d39a0a9f5 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 095f87645c..aa542181f9 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();
 
-- 
cgit 1.4.1