ZJIT: More type level docs in zjit::hir [DOC]

Given `InsnId` is at the top of the file and everywhere, hopefully this
will help first time readers.

Author: XrXr

zjit/src/hir.rs

@@ -1,4 +1,4 @@
-//! High level intermediary representation.
+//! High-level intermediary representation (IR) in static single-assignment (SSA) form.
 
 // We use the YARV bytecode constants which have a CRuby-style name
 #![allow(non_upper_case_globals)]
@@ -20,6 +20,7 @@ use std::{
 };
 use crate::hir_type::{Type, types};
 
+/// An index of an [`Insn`] in a [`Function`]. See also: [`Function::find`].
 #[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Hash, Debug)]
 pub struct InsnId(pub usize);
 
@@ -35,6 +36,7 @@ impl std::fmt::Display for InsnId {
     }
 }
 
+/// Reference to a [`Block`]. It's an index to help with circular reference.
 #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
 pub struct BlockId(pub usize);
 
@@ -309,11 +311,14 @@ impl PtrPrintMap {
     }
 }
 
+/// An instruction in the SSA IR. The output of an instruction is referred to by the index of
+/// the instruction ([`InsnId`]). SSA form enables this, and [`UnionFind`] ([`Function::find`])
+/// helps with editing.
 #[derive(Debug, Clone)]
 pub enum Insn {
     PutSelf,
     Const { val: Const },
-    // SSA block parameter. Also used for function parameters in the function's entry block.
+    /// SSA block parameter. Also used for function parameters in the function's entry block.
     Param { idx: usize },
 
     StringCopy { val: InsnId },
@@ -324,8 +329,8 @@ pub enum Insn {
     ArrayDup { val: InsnId, state: InsnId },
     ArrayMax { elements: Vec<InsnId>, state: InsnId },
 
-    // Check if the value is truthy and "return" a C boolean. In reality, we will likely fuse this
-    // with IfTrue/IfFalse in the backend to generate jcc.
+    /// Check if the value is truthy and "return" a C boolean. In reality, we will likely fuse this
+    /// with IfTrue/IfFalse in the backend to generate jcc.
     Test { val: InsnId },
     Defined { op_type: usize, obj: VALUE, pushval: VALUE, v: InsnId },
     GetConstantPath { ic: *const iseq_inline_constant_cache },
@@ -334,29 +339,29 @@ pub enum Insn {
     //SetIvar {},
     //GetIvar {},
 
-    // Own a FrameState so that instructions can look up their dominating FrameState when
-    // generating deopt side-exits and frame reconstruction metadata. Does not directly generate
-    // any code.
+    /// Own a FrameState so that instructions can look up their dominating FrameState when
+    /// generating deopt side-exits and frame reconstruction metadata. Does not directly generate
+    /// any code.
     Snapshot { state: FrameState },
 
-    // Unconditional jump
+    /// Unconditional jump
     Jump(BranchEdge),
 
-    // Conditional branch instructions
+    /// Conditional branch instructions
     IfTrue { val: InsnId, target: BranchEdge },
     IfFalse { val: InsnId, target: BranchEdge },
 
-    // Call a C function
-    // `name` is for printing purposes only
+    /// Call a C function
+    /// `name` is for printing purposes only
     CCall { cfun: *const u8, args: Vec<InsnId>, name: ID, return_type: Type, elidable: bool },
 
-    // Send without block with dynamic dispatch
-    // Ignoring keyword arguments etc for now
+    /// Send without block with dynamic dispatch
+    /// Ignoring keyword arguments etc for now
     SendWithoutBlock { self_val: InsnId, call_info: CallInfo, cd: *const rb_call_data, args: Vec<InsnId>, state: InsnId },
     Send { self_val: InsnId, call_info: CallInfo, cd: *const rb_call_data, blockiseq: IseqPtr, args: Vec<InsnId>, state: InsnId },
     SendWithoutBlockDirect { self_val: InsnId, call_info: CallInfo, cd: *const rb_call_data, iseq: IseqPtr, args: Vec<InsnId>, state: InsnId },
 
-    // Control flow instructions
+    /// Control flow instructions
     Return { val: InsnId },
 
     /// Fixnum +, -, *, /, %, ==, !=, <, <=, >, >=
@@ -530,6 +535,7 @@ impl std::fmt::Display for Insn {
     }
 }
 
+/// A basic block in a [`Function`].
 #[derive(Default, Debug)]
 pub struct Block {
     params: Vec<InsnId>,
@@ -548,6 +554,7 @@ impl Block {
     }
 }
 
+/// Pretty printer for [`Function`].
 pub struct FunctionPrinter<'a> {
     fun: &'a Function,
     display_snapshot: bool,
@@ -660,6 +667,7 @@ impl<T: Copy + Into<usize> + PartialEq> UnionFind<T> {
     }
 }
 
+/// A group of [`Insn`]s organized as a graph of [`Block`]s.
 #[derive(Debug)]
 pub struct Function {
     // ISEQ this function refers to