fix(tvix/eval): fix doc comment syntax where applicable r/4786

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>

2 files changed, 56 insertions, 53 deletions

diff --git a/tvix/eval/src/compiler/mod.rs b/tvix/eval/src/compiler/mod.rs
index 496f0aaf3207..314ae86d43e9 100644
--- a/tvix/eval/src/compiler/mod.rs
+++ b/tvix/eval/src/compiler/mod.rs
@@ -433,12 +433,13 @@ impl Compiler<'_, '_> {
         }
     }
 
-    // Compile list literals into equivalent bytecode. List
-    // construction is fairly simple, consisting of pushing code for
-    // each literal element and an instruction with the element count.
-    //
-    // The VM, after evaluating the code for each element, simply
-    // constructs the list from the given number of elements.
+    /// Compile list literals into equivalent bytecode. List
+    /// construction is fairly simple, consisting of pushing code for
+    /// each literal element and an instruction with the element
+    /// count.
+    ///
+    /// The VM, after evaluating the code for each element, simply
+    /// constructs the list from the given number of elements.
     fn compile_list(&mut self, slot: LocalIdx, node: ast::List) {
         let mut count = 0;
 
@@ -450,14 +451,14 @@ impl Compiler<'_, '_> {
         self.push_op(OpCode::OpList(Count(count)), &node);
     }
 
-    // Compile attribute set literals into equivalent bytecode.
-    //
-    // This is complicated by a number of features specific to Nix
-    // attribute sets, most importantly:
-    //
-    // 1. Keys can be dynamically constructed through interpolation.
-    // 2. Keys can refer to nested attribute sets.
-    // 3. Attribute sets can (optionally) be recursive.
+    /// Compile attribute set literals into equivalent bytecode.
+    ///
+    /// This is complicated by a number of features specific to Nix
+    /// attribute sets, most importantly:
+    ///
+    /// 1. Keys can be dynamically constructed through interpolation.
+    /// 2. Keys can refer to nested attribute sets.
+    /// 3. Attribute sets can (optionally) be recursive.
     fn compile_attr_set(&mut self, slot: LocalIdx, node: ast::AttrSet) {
         if node.rec_token().is_some() {
             todo!("recursive attribute sets are not yet implemented")
@@ -632,16 +633,18 @@ impl Compiler<'_, '_> {
         self.compile(slot, node.body().unwrap());
     }
 
-    // Compile conditional expressions using jumping instructions in the VM.
-    //
-    //                        ┌────────────────────┐
-    //                        │ 0  [ conditional ] │
-    //                        │ 1   JUMP_IF_FALSE →┼─┐
-    //                        │ 2  [  main body  ] │ │ Jump to else body if
-    //                       ┌┼─3─←     JUMP       │ │ condition is false.
-    //  Jump over else body  ││ 4  [  else body  ]←┼─┘
-    //  if condition is true.└┼─5─→     ...        │
-    //                        └────────────────────┘
+    /// Compile conditional expressions using jumping instructions in the VM.
+    ///
+    /// ```notrust
+    ///                        ┌────────────────────┐
+    ///                        │ 0  [ conditional ] │
+    ///                        │ 1   JUMP_IF_FALSE →┼─┐
+    ///                        │ 2  [  main body  ] │ │ Jump to else body if
+    ///                       ┌┼─3─←     JUMP       │ │ condition is false.
+    ///  Jump over else body  ││ 4  [  else body  ]←┼─┘
+    ///  if condition is true.└┼─5─→     ...        │
+    ///                        └────────────────────┘
+    /// ```
     fn compile_if_else(&mut self, slot: LocalIdx, node: ast::IfElse) {
         self.compile(slot, node.condition().unwrap());
         self.emit_force(&node.condition().unwrap());
@@ -663,7 +666,7 @@ impl Compiler<'_, '_> {
         self.patch_jump(else_idx); // patch jump *over* else body
     }
 
-    // Compile an `inherit` node of a `let`-expression.
+    /// Compile an `inherit` node of a `let`-expression.
     fn compile_let_inherit<I: Iterator<Item = ast::Inherit>>(
         &mut self,
         slot: LocalIdx,
@@ -714,11 +717,11 @@ impl Compiler<'_, '_> {
         }
     }
 
-    // Compile a standard `let ...; in ...` statement.
-    //
-    // Unless in a non-standard scope, the encountered values are
-    // simply pushed on the stack and their indices noted in the
-    // entries vector.
+    /// Compile a standard `let ...; in ...` statement.
+    ///
+    /// Unless in a non-standard scope, the encountered values are
+    /// simply pushed on the stack and their indices noted in the
+    /// entries vector.
     fn compile_let_in(&mut self, slot: LocalIdx, node: ast::LetIn) {
         self.begin_scope();
 
@@ -837,9 +840,9 @@ impl Compiler<'_, '_> {
         };
     }
 
-    // Compile `with` expressions by emitting instructions that
-    // pop/remove the indices of attribute sets that are implicitly in
-    // scope through `with` on the "with-stack".
+    /// Compile `with` expressions by emitting instructions that
+    /// pop/remove the indices of attribute sets that are implicitly
+    /// in scope through `with` on the "with-stack".
     fn compile_with(&mut self, slot: LocalIdx, node: ast::With) {
         self.begin_scope();
         // TODO: Detect if the namespace is just an identifier, and
@@ -1298,9 +1301,9 @@ impl Compiler<'_, '_> {
         }
     }
 
-    // Normalises identifier fragments into a single string vector for
-    // `let`-expressions; fails if fragments requiring dynamic computation
-    // are encountered.
+    /// Normalises identifier fragments into a single string vector
+    /// for `let`-expressions; fails if fragments requiring dynamic
+    /// computation are encountered.
     fn normalise_ident_path<I: Iterator<Item = ast::Attr>>(
         &self,
         path: I,
diff --git a/tvix/eval/src/compiler/scope.rs b/tvix/eval/src/compiler/scope.rs
index a7791b750af0..b6fa61e7759b 100644
--- a/tvix/eval/src/compiler/scope.rs
+++ b/tvix/eval/src/compiler/scope.rs
@@ -32,25 +32,25 @@ enum LocalName {
 /// Represents a single local already known to the compiler.
 #[derive(Debug)]
 pub struct Local {
-    // Identifier of this local. This is always a statically known
-    // value (Nix does not allow dynamic identifier names in locals),
-    // or a "phantom" value not accessible by users.
+    /// Identifier of this local. This is always a statically known
+    /// value (Nix does not allow dynamic identifier names in locals),
+    /// or a "phantom" value not accessible by users.
     name: LocalName,
 
-    // Source span at which this local was declared.
+    /// Source span at which this local was declared.
     pub span: codemap::Span,
 
-    // Scope depth of this local.
+    /// Scope depth of this local.
     pub depth: usize,
 
-    // Is this local initialised?
+    /// Is this local initialised?
     pub initialised: bool,
 
-    // Is this local known to have been used at all?
+    /// Is this local known to have been used at all?
     pub used: bool,
 
-    // Does this local need to be finalised after the enclosing scope
-    // is completely constructed?
+    /// Does this local need to be finalised after the enclosing scope
+    /// is completely constructed?
     pub needs_finaliser: bool,
 }
 
@@ -135,18 +135,18 @@ pub struct Scope {
     pub locals: Vec<Local>,
     pub upvalues: Vec<Upvalue>,
 
-    // How many scopes "deep" are these locals?
+    /// How many scopes "deep" are these locals?
     pub scope_depth: usize,
 
-    // Current size of the `with`-stack at runtime.
+    /// Current size of the `with`-stack at runtime.
     with_stack_size: usize,
 
-    // Users are allowed to override globally defined symbols like
-    // `true`, `false` or `null` in scopes. We call this "scope
-    // poisoning", as it requires runtime resolution of those tokens.
-    //
-    // To support this efficiently, the depth at which a poisoning
-    // occured is tracked here.
+    /// Users are allowed to override globally defined symbols like
+    /// `true`, `false` or `null` in scopes. We call this "scope
+    /// poisoning", as it requires runtime resolution of those tokens.
+    ///
+    /// To support this efficiently, the depth at which a poisoning
+    /// occured is tracked here.
     poisoned_tokens: HashMap<&'static str, usize>,
 }