Doc comment fixes

src/circuit/gadget/sinsemilla/chip.rs

@@ -35,36 +35,37 @@ mod hash_to_point;
 /// Configuration for the Sinsemilla hash chip
 #[derive(Eq, PartialEq, Clone, Debug)]
 pub struct SinsemillaConfig {
-    // Selector used in the lookup argument as well as Sinsemilla custom gates.
+    /// Selector used in the lookup argument as well as Sinsemilla custom gates.
     q_sinsemilla1: Selector,
-    // Fixed column used in Sinsemilla custom gates.
+    /// Fixed column used in Sinsemilla custom gates, to toggle behaviour at the ends of
+    /// message pieces.
     q_sinsemilla2: Column<Fixed>,
-    // Fixed column used to constrain hash initialization to be consistent with
-    // the y-coordinate of the domain Q.
+    /// Fixed column used to constrain hash initialization to be consistent with
+    /// the y-coordinate of the domain $Q$.
     fixed_y_q: Column<Fixed>,
-    // Advice column used to store the x-coordinate of the accumulator at each
-    // iteration of the hash.
+    /// Advice column used to store the x-coordinate of the accumulator at each
+    /// iteration of the hash.
     x_a: Column<Advice>,
-    // Advice column used to store the x-coordinate of the generator corresponding
-    // to the message word at each iteration of the hash. This is looked up in the
-    // generator table.
+    /// Advice column used to store the x-coordinate of the generator corresponding
+    /// to the message word at each iteration of the hash. This is looked up in the
+    /// generator table.
     x_p: Column<Advice>,
-    // Advice column used to load the message.
+    /// Advice column used to load the message.
     bits: Column<Advice>,
-    // Advice column used to store the lambda_1 intermediate value at each
-    // iteration.
+    /// Advice column used to store the $\lambda_1$ intermediate value at each
+    /// iteration.
     lambda_1: Column<Advice>,
-    // Advice column used to store the lambda_2 intermediate value at each
-    // iteration.
+    /// Advice column used to store the $\lambda_2$ intermediate value at each
+    /// iteration.
     lambda_2: Column<Advice>,
-    // The lookup table where (idx, x_p, y_p) are loaded for the 2^K generators
-    // of the Sinsemilla hash.
+    /// The lookup table where $(\mathsf{idx}, x_p, y_p)$ are loaded for the $2^K$
+    /// generators of the Sinsemilla hash.
     generator_table: GeneratorTableConfig,
-    // Fixed column shared by the whole circuit. This is used to load the
-    // x-coordinate of the domain Q, which is then constrained to equal the
-    // initial x_a.
+    /// Fixed column shared by the whole circuit. This is used to load the
+    /// x-coordinate of the domain $Q$, which is then constrained to equal the
+    /// initial $x_a$.
     constants: Column<Fixed>,
-    // Permutation over all advice columns and the `constants` fixed column.
+    /// Permutation over all advice columns and the `constants` fixed column.
     perm: Permutation,
 }
 

src/circuit/gadget/sinsemilla/chip/hash_to_point.rs

@@ -161,11 +161,12 @@ impl SinsemillaChip {
     }
 
     #[allow(clippy::type_complexity)]
-    // Hash a message piece containing `piece.length` number of `K`-bit words.
-    // To avoid a duplicate assignment, the accumulator x-coordinate provided
-    // by the caller is not copied. This only works because `hash_piece()` is
-    // an internal API. Before this call to `hash_piece()`, x_a MUST have been
-    // already assigned within this region at the correct offset.
+    /// Hashes a message piece containing `piece.length` number of `K`-bit words.
+    ///
+    /// To avoid a duplicate assignment, the accumulator x-coordinate provided
+    /// by the caller is not copied. This only works because `hash_piece()` is
+    /// an internal API. Before this call to `hash_piece()`, x_a MUST have been
+    /// already assigned within this region at the correct offset.
     fn hash_piece(
         &self,
         region: &mut Region<'_, pallas::Base>,
@@ -409,7 +410,7 @@ impl SinsemillaChip {
     }
 }
 
-// The x-coordinate of the accumulator in a Sinsemilla hash instance.
+/// The x-coordinate of the accumulator in a Sinsemilla hash instance.
 struct X<F: FieldExt>(CellValue<F>);
 
 impl<F: FieldExt> From<CellValue<F>> for X<F> {
@@ -426,10 +427,11 @@ impl<F: FieldExt> Deref for X<F> {
     }
 }
 
-// The y-coordinate of the accumulator in a Sinsemilla hash instance.
-// This is never actually witnessed until the last round, since it
-// can be derived from other variables. Thus it only exists as a field
-// element, not a `CellValue`.
+/// The y-coordinate of the accumulator in a Sinsemilla hash instance.
+///
+/// This is never actually witnessed until the last round, since it
+/// can be derived from other variables. Thus it only exists as a field
+/// element, not a `CellValue`.
 struct Y<F: FieldExt>(Option<F>);
 
 impl<F: FieldExt> From<Option<F>> for Y<F> {

src/circuit/gadget/sinsemilla/message.rs

@@ -36,7 +36,7 @@ impl<F: FieldExt + PrimeFieldBits, const K: usize, const MAX_WORDS: usize> std::
 pub struct MessagePiece<F: FieldExt, const K: usize> {
     cell: Cell,
     field_elem: Option<F>,
-    // The number of K-bit words in this message piece.
+    /// The number of K-bit words in this message piece.
     num_words: usize,
 }