Fix docs (easy) (microsoft#291)

* Improve rustdoc

- Updated references in documentation comments, changing from Kotlin-style to rustdoc style.
- Corrected the use of brackets to backticks for proper Rust code referencing in the comments in the `lib.rs` and `r1cs/mod.rs` files.
- The changes made were purely stylistic and cosmetic. No modifications were made to the actual code logic or implementation.

* doc: fix Rustdoc

- Updated hyperlink format in `HyperKZG` module documentation.
- CI should be testing this when rust-lang/rust#56232 resolves.

src/lib.rs

@@ -80,7 +80,7 @@ impl<E: Engine> R1CSWithArity<E> {
     }
   }
 
-  /// Return the [R1CSWithArity]' digest.
+  /// Return the [`R1CSWithArity`]' digest.
   pub fn digest(&self) -> E::Scalar {
     let dc: DigestComputer<'_, <E as Engine>::Scalar, Self> = DigestComputer::new(self);
     dc.digest().expect("Failure in computing digest")
@@ -1038,7 +1038,7 @@ where
   }
 }
 
-/// Compute the circuit digest of a [StepCircuit].
+/// Compute the circuit digest of a [`StepCircuit`].
 ///
 /// Note for callers: This function should be called with its performance characteristics in mind.
 /// It will synthesize and digest the full `circuit` given.

src/provider/hyperkzg.rs

@@ -1,5 +1,5 @@
 //! This module implements Nova's evaluation engine using `HyperKZG`, a KZG-based polynomial commitment for multilinear polynomials
-//! HyperKZG is based on the transformation from univariate PCS to multilinear PCS in the Gemini paper (section 2.4.2 in https://eprint.iacr.org/2022/420.pdf).
+//! HyperKZG is based on the transformation from univariate PCS to multilinear PCS in the Gemini paper (section 2.4.2 in `<https://eprint.iacr.org/2022/420.pdf>`).
 //! However, there are some key differences:
 //! (1) HyperKZG works with multilinear polynomials represented in evaluation form (rather than in coefficient form in Gemini's transformation).
 //! This means that Spartan's polynomial IOP can use commit to its polynomials as-is without incurring any interpolations or FFTs.

src/provider/non_hiding_kzg.rs

@@ -227,7 +227,7 @@ pub type UVKZGPoly<F> = crate::spartan::polys::univariate::UniPoly<F>;
 #[derive(Debug, Eq, PartialEq, Default)]
 /// KZG Polynomial Commitment Scheme on univariate polynomial.
 /// Note: this is non-hiding, which is why we will implement traits on this token struct,
-/// as we expect to have several impls for the trait pegged on the same instance of a pairing::Engine.
+/// as we expect to have several impls for the trait pegged on the same instance of a `pairing::Engine`.
 #[allow(clippy::upper_case_acronyms)]
 pub struct UVKZGPCS<E> {
   #[doc(hidden)]

src/provider/non_hiding_zeromorph.rs

@@ -128,8 +128,8 @@ pub struct ZMProof<E: Engine> {
 
 #[derive(Debug, Clone, Eq, PartialEq, Default)]
 /// Zeromorph Polynomial Commitment Scheme on multilinear polynomials.
-/// Note: this is non-hiding, which is why we will implement the EvaluationEngineTrait on this token struct,
-/// as we will have several impls for the trait pegged on the same instance of a pairing::Engine.
+/// Note: this is non-hiding, which is why we will implement the `EvaluationEngineTrait` on this token struct,
+/// as we will have several impls for the trait pegged on the same instance of a `pairing::Engine`.
 #[allow(clippy::upper_case_acronyms)]
 pub struct ZMPCS<E, NE> {
   #[doc(hidden)]
@@ -314,7 +314,7 @@ where
 ///
 /// where `poly(point)` is the evaluation of `poly` at `point`, and each `q_k` is a polynomial in `k` variables.
 ///
-/// Since our evaluations are presented in order reverse from the coefficients, if we want to interpret index q_k
+/// Since our evaluations are presented in order reverse from the coefficients, if we want to interpret index `q_k`
 /// to be the k-th coefficient in the polynomials returned here, the equality that holds is:
 ///
 /// ```text

src/provider/pedersen.rs

@@ -30,7 +30,7 @@ where
   ck: Vec<<E::GE as PrimeCurve>::Affine>,
 }
 
-/// [CommitmentKey]s are often large, and this helps with cloning bottlenecks
+/// [`CommitmentKey`]s are often large, and this helps with cloning bottlenecks
 impl<E> Clone for CommitmentKey<E>
 where
   E: Engine,

src/r1cs/mod.rs

@@ -160,7 +160,7 @@ impl<E: Engine> R1CSShape<E> {
     })
   }
 
-  /// Generate a random [R1CSShape] with the specified number of constraints, variables, and public inputs/outputs.
+  /// Generate a random [`R1CSShape`] with the specified number of constraints, variables, and public inputs/outputs.
   pub fn random<R: RngCore + CryptoRng>(
     num_cons: usize,
     num_vars: usize,
@@ -197,7 +197,7 @@ impl<E: Engine> R1CSShape<E> {
     }
   }
 
-  /// Generate a satisfying [RelaxedR1CSWitness] and [RelaxedR1CSInstance] for this [R1CSShape].
+  /// Generate a satisfying [`RelaxedR1CSWitness`] and [`RelaxedR1CSInstance`] for this [`R1CSShape`].
   pub fn random_witness_instance<R: RngCore + CryptoRng>(
     &self,
     commitment_key: &CommitmentKey<E>,

src/r1cs/sparse.rs

@@ -31,7 +31,7 @@ pub struct SparseMatrix<F: PrimeField> {
   pub cols: usize,
 }
 
-/// [SparseMatrix]s are often large, and this helps with cloning bottlenecks
+/// [`SparseMatrix`]s are often large, and this helps with cloning bottlenecks
 impl<F: PrimeField> Clone for SparseMatrix<F> {
   fn clone(&self) -> Self {
     Self {

src/spartan/sumcheck/engine.rs

@@ -31,7 +31,7 @@ pub trait SumcheckEngine<E: Engine>: Send + Sync {
   fn final_claims(&self) -> Vec<Vec<E::Scalar>>;
 }
 
-/// The [WitnessBoundSumcheck] ensures that the witness polynomial W defined over n = log(N) variables,
+/// The [`WitnessBoundSumcheck`] ensures that the witness polynomial W defined over n = log(N) variables,
 /// is zero outside of the first `num_vars = 2^m` entries.
 ///
 /// # Details
@@ -132,7 +132,7 @@ pub(in crate::spartan) struct MemorySumcheckInstance<E: Engine> {
 }
 
 impl<E: Engine> MemorySumcheckInstance<E> {
-  /// Computes witnesses for MemoryInstanceSumcheck
+  /// Computes witnesses for `MemoryInstanceSumcheck`
   ///
   /// # Description
   /// We use the logUp protocol to prove that
@@ -147,8 +147,8 @@ impl<E: Engine> MemorySumcheckInstance<E> {
   ///   W_col[i] = addr_col[i]     * gamma + addr_col[i]
   ///            = z[col[i]]       * gamma + addr_col[i]
   /// and
-  ///   TS_row, TS_col are integer-valued vectors representing the number of reads
-  ///   to each memory cell of L_row, L_col
+  ///   `TS_row`, `TS_col` are integer-valued vectors representing the number of reads
+  ///   to each memory cell of `L_row`, `L_col`
   ///
   /// The function returns oracles for the polynomials TS[i]/(T[i] + r), 1/(W[i] + r),
   /// as well as auxiliary polynomials T[i] + r, W[i] + r

src/supernova/mod.rs

@@ -67,19 +67,19 @@ impl<E: Engine> std::ops::Deref for CircuitDigests<E> {
 }
 
 impl<E: Engine> CircuitDigests<E> {
-  /// Construct a new [CircuitDigests]
+  /// Construct a new [`CircuitDigests`]
   pub fn new(digests: Vec<E::Scalar>) -> Self {
     Self { digests }
   }
 
-  /// Return the [CircuitDigests]' digest.
+  /// Return the [`CircuitDigests`]' digest.
   pub fn digest(&self) -> E::Scalar {
     let dc: DigestComputer<'_, <E as Engine>::Scalar, Self> = DigestComputer::new(self);
     dc.digest().expect("Failure in computing digest")
   }
 }
 
-/// A vector of [R1CSWithArity] adjoined to a set of [PublicParams]
+/// A vector of [`R1CSWithArity`] adjoined to a set of [`PublicParams`]
 #[derive(Debug, Serialize, Deserialize)]
 #[serde(bound = "")]
 pub struct PublicParams<E1, E2, C1, C2>
@@ -109,9 +109,9 @@ where
   _p: PhantomData<(C1, C2)>,
 }
 
-/// Auxiliary [PublicParams] information about the commitment keys and
+/// Auxiliary [`PublicParams`] information about the commitment keys and
 /// secondary circuit. This is used as a helper struct when reconstructing
-/// [PublicParams] downstream in lurk.
+/// [`PublicParams`] downstream in lurk.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(bound = "")]
 pub struct AuxParams<E1, E2>
@@ -244,7 +244,7 @@ where
   C1: StepCircuit<E1::Scalar>,
   C2: StepCircuit<E2::Scalar>,
 {
-  /// Construct a new [PublicParams]
+  /// Construct a new [`PublicParams`]
   ///
   /// # Note
   ///
@@ -344,7 +344,7 @@ where
     pp
   }
 
-  /// Breaks down an instance of [PublicParams] into the circuit params and auxiliary params.
+  /// Breaks down an instance of [`PublicParams`] into the circuit params and auxiliary params.
   pub fn into_parts(self) -> (Vec<R1CSWithArity<E1>>, AuxParams<E1, E2>) {
     let digest = self.digest();
 
@@ -379,7 +379,7 @@ where
     (circuit_shapes, aux_params)
   }
 
-  /// Create a [PublicParams] from a vector of raw [R1CSWithArity] and auxiliary params.
+  /// Create a [`PublicParams`] from a vector of raw [`R1CSWithArity`] and auxiliary params.
   pub fn from_parts(circuit_shapes: Vec<R1CSWithArity<E1>>, aux_params: AuxParams<E1, E2>) -> Self {
     let pp = Self {
       circuit_shapes,
@@ -403,7 +403,7 @@ where
     pp
   }
 
-  /// Create a [PublicParams] from a vector of raw [R1CSWithArity] and auxiliary params.
+  /// Create a [`PublicParams`] from a vector of raw [`R1CSWithArity`] and auxiliary params.
   /// We don't check that the `aux_params.digest` is a valid digest for the created params.
   pub fn from_parts_unchecked(
     circuit_shapes: Vec<R1CSWithArity<E1>>,
@@ -440,7 +440,7 @@ where
     E1::CE::setup(b"ck", size_primary)
   }
 
-  /// Return the [PublicParams]' digest.
+  /// Return the [`PublicParams`]' digest.
   pub fn digest(&self) -> E1::Scalar {
     self
       .digest
@@ -452,7 +452,7 @@ where
       .expect("Failure in retrieving digest")
   }
 
-  /// All of the primary circuit digests of this [PublicParams]
+  /// All of the primary circuit digests of this [`PublicParams`]
   pub fn circuit_param_digests(&self) -> CircuitDigests<E1> {
     let digests = self
       .circuit_shapes
@@ -1178,7 +1178,7 @@ where
 {
 }
 
-/// Compute the circuit digest of a supernova [StepCircuit].
+/// Compute the circuit digest of a supernova [`StepCircuit`].
 ///
 /// Note for callers: This function should be called with its performance characteristics in mind.
 /// It will synthesize and digest the full `circuit` given.

src/traits/evaluation.rs

@@ -28,7 +28,7 @@ pub trait EvaluationEngineTrait<E: Engine>: Clone + Send + Sync {
   /// A method to perform any additional setup needed to produce proofs of evaluations
   ///
   /// **Note:** This method should be cheap and should not copy most of the
-  /// commitment key. Look at CommitmentEngineTrait::setup for generating SRS data.
+  /// commitment key. Look at `CommitmentEngineTrait::setup` for generating SRS data.
   fn setup(
     ck: Arc<<<E as Engine>::CE as CommitmentEngineTrait<E>>::CommitmentKey>,
   ) -> (Self::ProverKey, Self::VerifierKey);

src/traits/mod.rs

@@ -117,7 +117,7 @@ pub trait ROCircuitTrait<Base: PrimeField> {
   ) -> Result<Vec<AllocatedBit>, SynthesisError>;
 }
 
-/// An alias for constants associated with E::RO
+/// An alias for constants associated with `E::RO`
 pub type ROConstants<E> =
   <<E as Engine>::RO as ROTrait<<E as Engine>::Base, <E as Engine>::Scalar>>::Constants;
 

src/traits/snark.rs

@@ -77,7 +77,7 @@ pub trait BatchedRelaxedR1CSSNARKTrait<E: Engine>:
   /// Produces the keys for the prover and the verifier
   ///
   /// **Note:** This method should be cheap and should not copy most of the
-  /// commitment key. Look at CommitmentEngineTrait::setup for generating SRS data.
+  /// commitment key. Look at `CommitmentEngineTrait::setup` for generating SRS data.
   fn setup(
     ck: Arc<CommitmentKey<E>>,
     S: Vec<&R1CSShape<E>>,