Convert regular comments to documentation comments.

lib/cretonne/src/dominator_tree.rs

@@ -11,28 +11,28 @@ use timing;
 use std::cmp::Ordering;
 use std::vec::Vec;
 
-// RPO numbers are not first assigned in a contiguous way but as multiples of STRIDE, to leave
-// room for modifications of the dominator tree.
+/// RPO numbers are not first assigned in a contiguous way but as multiples of STRIDE, to leave
+/// room for modifications of the dominator tree.
 const STRIDE: u32 = 4;
 
-// Special RPO numbers used during `compute_postorder`.
+/// Special RPO numbers used during `compute_postorder`.
 const DONE: u32 = 1;
 const SEEN: u32 = 2;
 
-// Dominator tree node. We keep one of these per EBB.
+/// Dominator tree node. We keep one of these per EBB.
 #[derive(Clone, Default)]
 struct DomNode {
-    // Number of this node in a reverse post-order traversal of the CFG, starting from 1.
-    // This number is monotonic in the reverse postorder but not contiguous, since we leave
-    // holes for later localized modifications of the dominator tree.
-    // Unreachable nodes get number 0, all others are positive.
+    /// Number of this node in a reverse post-order traversal of the CFG, starting from 1.
+    /// This number is monotonic in the reverse postorder but not contiguous, since we leave
+    /// holes for later localized modifications of the dominator tree.
+    /// Unreachable nodes get number 0, all others are positive.
     rpo_number: u32,
 
-    // The immediate dominator of this EBB, represented as the branch or jump instruction at the
-    // end of the dominating basic block.
-    //
-    // This is `None` for unreachable blocks and the entry block which doesn't have an immediate
-    // dominator.
+    /// The immediate dominator of this EBB, represented as the branch or jump instruction at the
+    /// end of the dominating basic block.
+    ///
+    /// This is `None` for unreachable blocks and the entry block which doesn't have an immediate
+    /// dominator.
     idom: PackedOption<Inst>,
 }
 
@@ -40,10 +40,10 @@ struct DomNode {
 pub struct DominatorTree {
     nodes: EntityMap<Ebb, DomNode>,
 
-    // CFG post-order of all reachable EBBs.
+    /// CFG post-order of all reachable EBBs.
     postorder: Vec<Ebb>,
 
-    // Scratch memory used by `compute_postorder()`.
+    /// Scratch memory used by `compute_postorder()`.
     stack: Vec<Ebb>,
 
     valid: bool,

lib/cretonne/src/ir/dfg.rs

@@ -348,18 +348,18 @@ impl ValueDef {
     }
 }
 
-// Internal table storage for extended values.
+/// Internal table storage for extended values.
 #[derive(Clone, Debug)]
 enum ValueData {
-    // Value is defined by an instruction.
+    /// Value is defined by an instruction.
     Inst { ty: Type, num: u16, inst: Inst },
 
-    // Value is an EBB parameter.
+    /// Value is an EBB parameter.
     Param { ty: Type, num: u16, ebb: Ebb },
 
-    // Value is an alias of another value.
-    // An alias value can't be linked as an instruction result or EBB parameter. It is used as a
-    // placeholder when the original instruction or EBB has been rewritten or modified.
+    /// Value is an alias of another value.
+    /// An alias value can't be linked as an instruction result or EBB parameter. It is used as a
+    /// placeholder when the original instruction or EBB has been rewritten or modified.
     Alias { ty: Type, original: Value },
 }
 
@@ -829,14 +829,14 @@ impl DataFlowGraph {
     }
 }
 
-// Contents of an extended basic block.
-//
-// Parameters on an extended basic block are values that dominate everything in the EBB. All
-// branches to this EBB must provide matching arguments, and the arguments to the entry EBB must
-// match the function arguments.
+/// Contents of an extended basic block.
+///
+/// Parameters on an extended basic block are values that dominate everything in the EBB. All
+/// branches to this EBB must provide matching arguments, and the arguments to the entry EBB must
+/// match the function arguments.
 #[derive(Clone)]
 struct EbbData {
-    // List of parameters to this EBB.
+    /// List of parameters to this EBB.
     params: ValueList,
 }
 

lib/cretonne/src/ir/immediates.rs

@@ -35,12 +35,12 @@ impl From<i64> for Imm64 {
     }
 }
 
-// Hexadecimal with a multiple of 4 digits and group separators:
-//
-//   0xfff0
-//   0x0001_ffff
-//   0xffff_ffff_fff8_4400
-//
+/// Hexadecimal with a multiple of 4 digits and group separators:
+///
+///   0xfff0
+///   0x0001_ffff
+///   0xffff_ffff_fff8_4400
+///
 fn write_hex(x: i64, f: &mut Formatter) -> fmt::Result {
     let mut pos = (64 - x.leading_zeros() - 1) & 0xf0;
     write!(f, "0x{:04x}", (x >> pos) & 0xffff)?;
@@ -280,16 +280,16 @@ pub struct Ieee32(u32);
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 pub struct Ieee64(u64);
 
-// Format a floating point number in a way that is reasonably human-readable, and that can be
-// converted back to binary without any rounding issues. The hexadecimal formatting of normal and
-// subnormal numbers is compatible with C99 and the `printf "%a"` format specifier. The NaN and Inf
-// formats are not supported by C99.
-//
-// The encoding parameters are:
-//
-// w - exponent field width in bits
-// t - trailing significand field width in bits
-//
+/// Format a floating point number in a way that is reasonably human-readable, and that can be
+/// converted back to binary without any rounding issues. The hexadecimal formatting of normal and
+/// subnormal numbers is compatible with C99 and the `printf "%a"` format specifier. The NaN and Inf
+/// formats are not supported by C99.
+///
+/// The encoding parameters are:
+///
+/// w - exponent field width in bits
+/// t - trailing significand field width in bits
+///
 fn format_float(bits: u64, w: u8, t: u8, f: &mut Formatter) -> fmt::Result {
     debug_assert!(w > 0 && w <= 16, "Invalid exponent range");
     debug_assert!(1 + w + t <= 64, "Too large IEEE format for u64");
@@ -358,13 +358,13 @@ fn format_float(bits: u64, w: u8, t: u8, f: &mut Formatter) -> fmt::Result {
     }
 }
 
-// Parse a float using the same format as `format_float` above.
-//
-// The encoding parameters are:
-//
-// w - exponent field width in bits
-// t - trailing significand field width in bits
-//
+/// Parse a float using the same format as `format_float` above.
+///
+/// The encoding parameters are:
+///
+/// w - exponent field width in bits
+/// t - trailing significand field width in bits
+///
 fn parse_float(s: &str, w: u8, t: u8) -> Result<u64, &'static str> {
     debug_assert!(w > 0 && w <= 16, "Invalid exponent range");
     debug_assert!(1 + w + t <= 64, "Too large IEEE format for u64");

lib/cretonne/src/ir/layout.rs

@@ -26,18 +26,18 @@ use timing;
 ///
 #[derive(Clone)]
 pub struct Layout {
-    // Linked list nodes for the layout order of EBBs Forms a doubly linked list, terminated in
-    // both ends by `None`.
+    /// Linked list nodes for the layout order of EBBs Forms a doubly linked list, terminated in
+    /// both ends by `None`.
     ebbs: EntityMap<Ebb, EbbNode>,
 
-    // Linked list nodes for the layout order of instructions. Forms a double linked list per EBB,
-    // terminated in both ends by `None`.
+    /// Linked list nodes for the layout order of instructions. Forms a double linked list per EBB,
+    /// terminated in both ends by `None`.
     insts: EntityMap<Inst, InstNode>,
 
-    // First EBB in the layout order, or `None` when no EBBs have been laid out.
+    /// First EBB in the layout order, or `None` when no EBBs have been laid out.
     first_ebb: Option<Ebb>,
 
-    // Last EBB in the layout order, or `None` when no EBBs have been laid out.
+    /// Last EBB in the layout order, or `None` when no EBBs have been laid out.
     last_ebb: Option<Ebb>,
 }
 
@@ -61,31 +61,31 @@ impl Layout {
     }
 }
 
-// Sequence numbers.
-//
-// All instructions and EBBs are given a sequence number that can be used to quickly determine
-// their relative position in the layout. The sequence numbers are not contiguous, but are assigned
-// like line numbers in BASIC: 10, 20, 30, ...
-//
-// The EBB sequence numbers are strictly increasing, and so are the instruction sequence numbers
-// within an EBB. The instruction sequence numbers are all between the sequence number of their
-// containing EBB and the following EBB.
-//
-// The result is that sequence numbers work like BASIC line numbers for the textual form of the IR.
+/// Sequence numbers.
+///
+/// All instructions and EBBs are given a sequence number that can be used to quickly determine
+/// their relative position in the layout. The sequence numbers are not contiguous, but are assigned
+/// like line numbers in BASIC: 10, 20, 30, ...
+///
+/// The EBB sequence numbers are strictly increasing, and so are the instruction sequence numbers
+/// within an EBB. The instruction sequence numbers are all between the sequence number of their
+/// containing EBB and the following EBB.
+///
+/// The result is that sequence numbers work like BASIC line numbers for the textual form of the IR.
 type SequenceNumber = u32;
 
-// Initial stride assigned to new sequence numbers.
+/// Initial stride assigned to new sequence numbers.
 const MAJOR_STRIDE: SequenceNumber = 10;
 
-// Secondary stride used when renumbering locally.
+/// Secondary stride used when renumbering locally.
 const MINOR_STRIDE: SequenceNumber = 2;
 
-// Limit on the sequence number range we'll renumber locally. If this limit is exceeded, we'll
-// switch to a full function renumbering.
+/// Limit on the sequence number range we'll renumber locally. If this limit is exceeded, we'll
+/// switch to a full function renumbering.
 const LOCAL_LIMIT: SequenceNumber = 100 * MINOR_STRIDE;
 
-// Compute the midpoint between `a` and `b`.
-// Return `None` if the midpoint would be equal to either.
+/// Compute the midpoint between `a` and `b`.
+/// Return `None` if the midpoint would be equal to either.
 fn midpoint(a: SequenceNumber, b: SequenceNumber) -> Option<SequenceNumber> {
     debug_assert!(a < b);
     // Avoid integer overflow.

lib/cretonne/src/ir/types.rs

@@ -24,10 +24,10 @@ pub struct Type(u8);
 /// a SIMD vector.
 pub const VOID: Type = Type(0);
 
-// Start of the lane types. See also `meta/cdsl.types.py`.
+/// Start of the lane types. See also `meta/cdsl.types.py`.
 const LANE_BASE: u8 = 0x70;
 
-// Start of the 2-lane vector types.
+/// Start of the 2-lane vector types.
 const VECTOR_BASE: u8 = LANE_BASE + 16;
 
 // Include code generated by `lib/cretonne/meta/gen_types.py`. This file contains constant

lib/cretonne/src/regalloc/spilling.rs

@@ -548,8 +548,8 @@ impl<'a> Context<'a> {
     }
 }
 
-// Struct representing a register use of a value.
-// Used to detect multiple uses of the same value with incompatible register constraints.
+/// Struct representing a register use of a value.
+/// Used to detect multiple uses of the same value with incompatible register constraints.
 #[derive(Clone, Copy)]
 struct RegUse {
     value: Value,

lib/filetests/src/concurrent.rs

@@ -13,7 +13,7 @@ use std::time::Duration;
 use num_cpus;
 use {TestResult, runone};
 
-// Request sent to worker threads contains jobid and path.
+/// Request sent to worker threads contains jobid and path.
 struct Request(usize, PathBuf);
 
 /// Reply from worker thread,
@@ -25,13 +25,13 @@ pub enum Reply {
 
 /// Manage threads that run test jobs concurrently.
 pub struct ConcurrentRunner {
-    // Channel for sending requests to the worker threads.
-    // The workers are sharing the receiver with an `Arc<Mutex<Receiver>>`.
-    // This is `None` when shutting down.
+    /// Channel for sending requests to the worker threads.
+    /// The workers are sharing the receiver with an `Arc<Mutex<Receiver>>`.
+    /// This is `None` when shutting down.
     request_tx: Option<Sender<Request>>,
 
-    // Channel for receiving replies from the workers.
-    // Workers have their own `Sender`.
+    /// Channel for receiving replies from the workers.
+    /// Workers have their own `Sender`.
     reply_rx: Receiver<Reply>,
 
     handles: Vec<thread::JoinHandle<timing::PassTimes>>,

lib/filetests/src/runner.rs

@@ -11,10 +11,10 @@ use std::time;
 use {TestResult, runone};
 use concurrent::{ConcurrentRunner, Reply};
 
-// Timeout in seconds when we're not making progress.
+/// Timeout in seconds when we're not making progress.
 const TIMEOUT_PANIC: usize = 10;
 
-// Timeout for reporting slow tests without panicking.
+/// Timeout for reporting slow tests without panicking.
 const TIMEOUT_SLOW: usize = 3;
 
 struct QueueEntry {

lib/filetests/src/test_binemit.rs

@@ -27,7 +27,7 @@ pub fn subtest(parsed: &TestCommand) -> Result<Box<SubTest>> {
     }
 }
 
-// Code sink that generates text.
+/// Code sink that generates text.
 struct TextSink {
     offset: binemit::CodeOffset,
     text: String,

lib/filetests/src/test_compile.rs

@@ -76,7 +76,7 @@ impl SubTest for TestCompile {
     }
 }
 
-// Code sink that simply counts bytes.
+/// Code sink that simply counts bytes.
 struct SizeSink {
     offset: binemit::CodeOffset,
 }

lib/frontend/src/ssa.rs

@@ -77,12 +77,12 @@ impl SideEffects {
     }
 }
 
-// Describes the current position of a basic block in the control flow graph.
+/// Describes the current position of a basic block in the control flow graph.
 enum BlockData<Variable> {
-    // A block at the top of an `Ebb`.
+    /// A block at the top of an `Ebb`.
     EbbHeader(EbbHeaderBlockData<Variable>),
-    // A block inside an `Ebb` with an unique other block as its predecessor.
-    // The block is implicitly sealed at creation.
+    /// A block inside an `Ebb` with an unique other block as its predecessor.
+    /// The block is implicitly sealed at creation.
     EbbBody { predecessor: Block },
 }
 
@@ -179,7 +179,7 @@ where
     }
 }
 
-// Small enum used for clarity in some functions.
+/// Small enum used for clarity in some functions.
 #[derive(Debug)]
 enum ZeroOneOrMore<T> {
     Zero(),
@@ -194,7 +194,7 @@ enum UseVarCases {
     SealedMultiplePredecessors(Value, Ebb),
 }
 
-// States for the `use_var`/`predecessors_lookup` state machine.
+/// States for the `use_var`/`predecessors_lookup` state machine.
 enum Call {
     UseVar(Block),
     FinishSealedOnePredecessor(Block),

lib/reader/src/parser.rs

@@ -65,34 +65,34 @@ pub struct Parser<'a> {
 
     lex_error: Option<lexer::Error>,
 
-    // Current lookahead token.
+    /// Current lookahead token.
     lookahead: Option<Token<'a>>,
 
-    // Location of lookahead.
+    /// Location of lookahead.
     loc: Location,
 
-    // Are we gathering any comments that we encounter?
+    /// Are we gathering any comments that we encounter?
     gathering_comments: bool,
 
-    // The gathered comments; claim them with `claim_gathered_comments`.
+    /// The gathered comments; claim them with `claim_gathered_comments`.
     gathered_comments: Vec<&'a str>,
 
-    // Comments collected so far.
+    /// Comments collected so far.
     comments: Vec<Comment<'a>>,
 }
 
-// Context for resolving references when parsing a single function.
+/// Context for resolving references when parsing a single function.
 struct Context<'a> {
     function: Function,
     map: SourceMap,
 
-    // Aliases to resolve once value definitions are known.
+    /// Aliases to resolve once value definitions are known.
     aliases: Vec<Value>,
 
-    // Reference to the unique_isa for things like parsing ISA-specific instruction encoding
-    // information. This is only `Some` if exactly one set of `isa` directives were found in the
-    // prologue (it is valid to have directives for multiple different ISAs, but in that case we
-    // couldn't know which ISA the provided encodings are intended for)
+    /// Reference to the unique_isa for things like parsing ISA-specific instruction encoding
+    /// information. This is only `Some` if exactly one set of `isa` directives were found in the
+    /// prologue (it is valid to have directives for multiple different ISAs, but in that case we
+    /// couldn't know which ISA the provided encodings are intended for)
     unique_isa: Option<&'a TargetIsa>,
 }
 

lib/wasm/src/code_translator.rs

@@ -944,7 +944,7 @@ fn translate_unreachable_operator(
     }
 }
 
-// Get the address+offset to use for a heap access.
+/// Get the address+offset to use for a heap access.
 fn get_heap_addr(
     heap: ir::Heap,
     addr32: ir::Value,
@@ -981,7 +981,7 @@ fn get_heap_addr(
     }
 }
 
-// Translate a load instruction.
+/// Translate a load instruction.
 fn translate_load<FE: FuncEnvironment + ?Sized>(
     offset: u32,
     opcode: ir::Opcode,
@@ -1008,7 +1008,7 @@ fn translate_load<FE: FuncEnvironment + ?Sized>(
     state.push1(dfg.first_result(load));
 }
 
-// Translate a store instruction.
+/// Translate a store instruction.
 fn translate_store<FE: FuncEnvironment + ?Sized>(
     offset: u32,
     opcode: ir::Opcode,