improve on documentation: more and better links

triton-opcodes/src/instruction.rs

@@ -26,7 +26,7 @@ pub type Instruction = AnInstruction<BFieldElement>;
 pub enum LabelledInstruction {
     /// Instructions belong to the ISA:
     ///
-    /// https://triton-vm.org/spec/isa.html
+    /// <https://triton-vm.org/spec/isa.html>
     Instruction(AnInstruction<String>),
 
     /// Labels look like "`<name>:`" and are translated into absolute addresses.

triton-vm/src/table/challenges.rs

@@ -1,5 +1,8 @@
-//! Challenges are needed for the cross-table arguments, _i.e._, Permutation Arguments, Evaluation
-//! Arguments, and Lookup Arguments, as well as for the RAM Table's Contiguity Argument.
+//! Challenges are needed for the [cross-table arguments](CrossTableArg), _i.e._,
+//! [Permutation Arguments](crate::table::cross_table_argument::PermArg),
+//! [Evaluation Arguments](crate::table::cross_table_argument::EvalArg), and
+//! [Lookup Arguments](crate::table::cross_table_argument::LookupArg),
+//! as well as for the RAM Table's Contiguity Argument.
 //!
 //! There are three types of challenges:
 //! - **Weights**. Weights are used to non-linearly combine multiple elements into one element. The
@@ -31,23 +34,25 @@ use crate::table::cross_table_argument::CrossTableArg;
 use crate::table::cross_table_argument::EvalArg;
 
 /// A `ChallengeId` is a unique, symbolic identifier for a challenge used in Triton VM. The
-/// `ChallengeId` enum works in tandem with the struct `Challenges`, which can be
+/// `ChallengeId` enum works in tandem with the struct [`Challenges`], which can be
 /// instantiated to hold actual challenges that can be indexed by some `ChallengeId`.
 ///
 /// Since almost all challenges relate to the Processor Table in some form, the words “Processor
 /// Table” are usually omitted from the `ChallengeId`'s name.
 #[repr(usize)]
 #[derive(Display, Debug, Clone, Copy, PartialEq, Eq, EnumIter, EnumCountMacro, Hash)]
 pub enum ChallengeId {
-    /// The indeterminate for the Evaluation Argument with standard input.
+    /// The indeterminate for the [Evaluation Argument](EvalArg) with standard input.
     StandardInputIndeterminate,
 
-    /// The indeterminate for the Evaluation Argument with standard output.
+    /// The indeterminate for the [Evaluation Argument](EvalArg) with standard output.
     StandardOutputIndeterminate,
 
-    /// The indeterminate for the instruction Lookup Argument between the Processor Table and the
-    /// Program Table guaranteeing that the instructions and their arguments are copied
-    /// correctly.
+    /// The indeterminate for the instruction
+    /// [Lookup Argument](crate::table::cross_table_argument::LookupArg)
+    /// between the [Processor Table](crate::table::processor_table) and the
+    /// [Program Table](crate::table::program_table) guaranteeing that the instructions and their
+    /// arguments are copied correctly.
     InstructionLookupIndeterminate,
 
     HashInputIndeterminate,
@@ -148,8 +153,8 @@ impl ChallengeId {
 }
 
 /// The `Challenges` struct holds the challenges used in Triton VM. The concrete challenges are
-/// known only at runtime. The challenges are indexed using enum `ChallengeId`. The `Challenges`
-/// struct is essentially a thin wrapper around an array of `XFieldElement`s, providing
+/// known only at runtime. The challenges are indexed using enum [`ChallengeId`]. The `Challenges`
+/// struct is essentially a thin wrapper around an array of [`XFieldElement`]s, providing
 /// convenience methods.
 pub struct Challenges {
     pub challenges: [XFieldElement; Self::count()],

triton-vm/src/table/cross_table_argument.rs

@@ -48,7 +48,7 @@ impl CrossTableArg for PermArg {
     /// Compute the product for a permutation argument as specified by `initial`, `challenge`,
     /// and `symbols`. This amounts to evaluating polynomial
     ///  `f(x) = initial · Π_i (x - symbols[i])`
-    /// at point `challenge`, i.e., returns `f(challenge)`.
+    /// at point `challenge`, _i.e._, returns `f(challenge)`.
     fn compute_terminal(
         symbols: &[BFieldElement],
         initial: XFieldElement,
@@ -72,7 +72,7 @@ impl CrossTableArg for EvalArg {
     /// Compute the evaluation for an evaluation argument as specified by `initial`, `challenge`,
     /// and `symbols`. This amounts to evaluating polynomial
     /// `f(x) = initial·x^n + Σ_i symbols[n-i]·x^i`
-    /// at point `challenge`, i.e., returns `f(challenge)`.
+    /// at point `challenge`, _i.e._, returns `f(challenge)`.
     fn compute_terminal(
         symbols: &[BFieldElement],
         initial: XFieldElement,