Doxygenize the documentation comments

src/IceInst.h

Index: src/IceInst.h
diff --git a/src/IceInst.h b/src/IceInst.h
index 7aad05455aa7d7519f671eb99ee7c38334324861..186282a9e411cf2d816140a8df2da72a7e1ce1b0 100644
--- a/src/IceInst.h
+++ b/src/IceInst.h
@@ -31,10 +31,10 @@
 
 namespace Ice {
 
-// Base instruction class for ICE.  Inst has two subclasses:
-// InstHighLevel and InstTarget.  High-level ICE instructions inherit
-// from InstHighLevel, and low-level (target-specific) ICE
-// instructions inherit from InstTarget.
+/// Base instruction class for ICE.  Inst has two subclasses:
+/// InstHighLevel and InstTarget.  High-level ICE instructions inherit
+/// from InstHighLevel, and low-level (target-specific) ICE
+/// instructions inherit from InstTarget.
 class Inst : public llvm::ilist_node<Inst> {
   Inst() = delete;
   Inst(const Inst &) = delete;
@@ -105,8 +105,8 @@ public:
   bool isLastUse(const Operand *Src) const;
   void spliceLivenessInfo(Inst *OrigInst, Inst *SpliceAssn);
 
-  // Returns a list of out-edges corresponding to a terminator
-  // instruction, which is the last instruction of the block.
+  /// Returns a list of out-edges corresponding to a terminator
+  /// instruction, which is the last instruction of the block.
   virtual NodeList getTerminatorEdges() const {
     // All valid terminator instructions override this method.  For
     // the default implementation, we assert in case some CfgNode
@@ -116,10 +116,10 @@ public:
     return NodeList();
   }
   virtual bool isUnconditionalBranch() const { return false; }
-  // If the instruction is a branch-type instruction with OldNode as a
-  // target, repoint it to NewNode and return true, otherwise return
-  // false.  Only repoint one instance, even if the instruction has
-  // multiple instances of OldNode as a target.
+  /// If the instruction is a branch-type instruction with OldNode as a
+  /// target, repoint it to NewNode and return true, otherwise return
+  /// false.  Only repoint one instance, even if the instruction has
+  /// multiple instances of OldNode as a target.
   virtual bool repointEdge(CfgNode *OldNode, CfgNode *NewNode) {
     (void)OldNode;
     (void)NewNode;
@@ -129,19 +129,19 @@ public:
   virtual bool isSimpleAssign() const { return false; }
 
   void livenessLightweight(Cfg *Func, LivenessBV &Live);
-  // Calculates liveness for this instruction.  Returns true if this
-  // instruction is (tentatively) still live and should be retained,
-  // and false if this instruction is (tentatively) dead and should be
-  // deleted.  The decision is tentative until the liveness dataflow
-  // algorithm has converged, and then a separate pass permanently
-  // deletes dead instructions.
+  /// Calculates liveness for this instruction.  Returns true if this
+  /// instruction is (tentatively) still live and should be retained,
+  /// and false if this instruction is (tentatively) dead and should be
+  /// deleted.  The decision is tentative until the liveness dataflow
+  /// algorithm has converged, and then a separate pass permanently
+  /// deletes dead instructions.
   bool liveness(InstNumberT InstNumber, LivenessBV &Live, Liveness *Liveness,
                 LiveBeginEndMap *LiveBegin, LiveBeginEndMap *LiveEnd);
 
-  // Get the number of native instructions that this instruction
-  // ultimately emits.  By default, high-level instructions don't
-  // result in any native instructions, and a target-specific
-  // instruction results in a single native instruction.
+  /// Get the number of native instructions that this instruction
+  /// ultimately emits.  By default, high-level instructions don't
+  /// result in any native instructions, and a target-specific
+  /// instruction results in a single native instruction.
   virtual uint32_t getEmitInstCount() const { return 0; }
   // TODO(stichnot): Change Inst back to abstract once the g++ build
   // issue is fixed.  llvm::ilist<Ice::Inst> doesn't work under g++
@@ -179,26 +179,26 @@ protected:
       LiveRangesEnded |= (((LREndedBits)1u) << VarIndex);
   }
   void resetLastUses() { LiveRangesEnded = 0; }
-  // The destroy() method lets the instruction cleanly release any
-  // memory that was allocated via the Cfg's allocator.
+  /// The destroy() method lets the instruction cleanly release any
+  /// memory that was allocated via the Cfg's allocator.
   virtual void destroy(Cfg *Func) { Func->deallocateArrayOf<Operand *>(Srcs); }
 
   const InstKind Kind;
-  // Number is the instruction number for describing live ranges.
+  /// Number is the instruction number for describing live ranges.
   InstNumberT Number;
-  // Deleted means irrevocably deleted.
+  /// Deleted means irrevocably deleted.
   bool Deleted = false;
-  // Dead means one of two things depending on context: (1) pending
-  // deletion after liveness analysis converges, or (2) marked for
-  // deletion during lowering due to a folded bool operation.
+  /// Dead means one of two things depending on context: (1) pending
+  /// deletion after liveness analysis converges, or (2) marked for
+  /// deletion during lowering due to a folded bool operation.
   bool Dead = false;
-  // HasSideEffects means the instruction is something like a function
-  // call or a volatile load that can't be removed even if its Dest
-  // variable is not live.
+  /// HasSideEffects means the instruction is something like a function
+  /// call or a volatile load that can't be removed even if its Dest
+  /// variable is not live.
   bool HasSideEffects = false;
-  // IsDestNonKillable means that liveness analysis shouldn't consider
-  // this instruction to kill the Dest variable.  This is used when
-  // lowering produces two assignments to the same variable.
+  /// IsDestNonKillable means that liveness analysis shouldn't consider
+  /// this instruction to kill the Dest variable.  This is used when
+  /// lowering produces two assignments to the same variable.
   bool IsDestNonKillable = false;
 
   Variable *Dest;
@@ -206,15 +206,15 @@ protected:
   SizeT NumSrcs = 0;
   Operand **Srcs;
 
-  // LiveRangesEnded marks which Variables' live ranges end in this
-  // instruction.  An instruction can have an arbitrary number of
-  // source operands (e.g. a call instruction), and each source
-  // operand can contain 0 or 1 Variable (and target-specific operands
-  // could contain more than 1 Variable).  All the variables in an
-  // instruction are conceptually flattened and each variable is
-  // mapped to one bit position of the LiveRangesEnded bit vector.
-  // Only the first CHAR_BIT * sizeof(LREndedBits) variables are
-  // tracked this way.
+  /// LiveRangesEnded marks which Variables' live ranges end in this
+  /// instruction.  An instruction can have an arbitrary number of
+  /// source operands (e.g. a call instruction), and each source
+  /// operand can contain 0 or 1 Variable (and target-specific operands
+  /// could contain more than 1 Variable).  All the variables in an
+  /// instruction are conceptually flattened and each variable is
+  /// mapped to one bit position of the LiveRangesEnded bit vector.
+  /// Only the first CHAR_BIT * sizeof(LREndedBits) variables are
+  /// tracked this way.
   typedef uint32_t LREndedBits; // only first 32 src operands tracked, sorry
   LREndedBits LiveRangesEnded;
 };
@@ -235,9 +235,9 @@ protected:
   }
 };
 
-// Alloca instruction.  This captures the size in bytes as getSrc(0),
-// and the required alignment in bytes.  The alignment must be either
-// 0 (no alignment required) or a power of 2.
+/// Alloca instruction.  This captures the size in bytes as getSrc(0),
+/// and the required alignment in bytes.  The alignment must be either
+/// 0 (no alignment required) or a power of 2.
 class InstAlloca : public InstHighLevel {
   InstAlloca() = delete;
   InstAlloca(const InstAlloca &) = delete;
@@ -261,8 +261,8 @@ private:
   const uint32_t AlignInBytes;
 };
 
-// Binary arithmetic instruction.  The source operands are captured in
-// getSrc(0) and getSrc(1).
+/// Binary arithmetic instruction.  The source operands are captured in
+/// getSrc(0) and getSrc(1).
 class InstArithmetic : public InstHighLevel {
   InstArithmetic() = delete;
   InstArithmetic(const InstArithmetic &) = delete;
@@ -296,12 +296,12 @@ private:
   const OpKind Op;
 };
 
-// Assignment instruction.  The source operand is captured in
-// getSrc(0).  This is not part of the LLVM bitcode, but is a useful
-// abstraction for some of the lowering.  E.g., if Phi instruction
-// lowering happens before target lowering, or for representing an
-// Inttoptr instruction, or as an intermediate step for lowering a
-// Load instruction.
+/// Assignment instruction.  The source operand is captured in
+/// getSrc(0).  This is not part of the LLVM bitcode, but is a useful
+/// abstraction for some of the lowering.  E.g., if Phi instruction
+/// lowering happens before target lowering, or for representing an
+/// Inttoptr instruction, or as an intermediate step for lowering a
+/// Load instruction.
 class InstAssign : public InstHighLevel {
   InstAssign() = delete;
   InstAssign(const InstAssign &) = delete;
@@ -319,22 +319,22 @@ private:
   InstAssign(Cfg *Func, Variable *Dest, Operand *Source);
 };
 
-// Branch instruction.  This represents both conditional and
-// unconditional branches.
+/// Branch instruction.  This represents both conditional and
+/// unconditional branches.
 class InstBr : public InstHighLevel {
   InstBr() = delete;
   InstBr(const InstBr &) = delete;
   InstBr &operator=(const InstBr &) = delete;
 
 public:
-  // Create a conditional branch.  If TargetTrue==TargetFalse, it is
-  // optimized to an unconditional branch.
+  /// Create a conditional branch.  If TargetTrue==TargetFalse, it is
+  /// optimized to an unconditional branch.
   static InstBr *create(Cfg *Func, Operand *Source, CfgNode *TargetTrue,
                         CfgNode *TargetFalse) {
     return new (Func->allocate<InstBr>())
         InstBr(Func, Source, TargetTrue, TargetFalse);
   }
-  // Create an unconditional branch.
+  /// Create an unconditional branch.
   static InstBr *create(Cfg *Func, CfgNode *Target) {
     return new (Func->allocate<InstBr>()) InstBr(Func, Target);
   }
@@ -356,17 +356,17 @@ public:
   static bool classof(const Inst *Inst) { return Inst->getKind() == Br; }
 
 private:
-  // Conditional branch
+  /// Conditional branch
   InstBr(Cfg *Func, Operand *Source, CfgNode *TargetTrue, CfgNode *TargetFalse);
-  // Unconditional branch
+  /// Unconditional branch
   InstBr(Cfg *Func, CfgNode *Target);
 
-  CfgNode *TargetFalse; // Doubles as unconditional branch target
-  CfgNode *TargetTrue;  // nullptr if unconditional branch
+  CfgNode *TargetFalse; /// Doubles as unconditional branch target
+  CfgNode *TargetTrue;  /// nullptr if unconditional branch
 };
 
-// Call instruction.  The call target is captured as getSrc(0), and
-// arg I is captured as getSrc(I+1).
+/// Call instruction.  The call target is captured as getSrc(0), and
+/// arg I is captured as getSrc(I+1).
 class InstCall : public InstHighLevel {
   InstCall() = delete;
   InstCall(const InstCall &) = delete;
@@ -375,9 +375,9 @@ class InstCall : public InstHighLevel {
 public:
   static InstCall *create(Cfg *Func, SizeT NumArgs, Variable *Dest,
                           Operand *CallTarget, bool HasTailCall) {
-    // Set HasSideEffects to true so that the call instruction can't be
-    // dead-code eliminated. IntrinsicCalls can override this if the
-    // particular intrinsic is deletable and has no side-effects.
+    /// Set HasSideEffects to true so that the call instruction can't be
+    /// dead-code eliminated. IntrinsicCalls can override this if the
+    /// particular intrinsic is deletable and has no side-effects.
     const bool HasSideEffects = true;
     const InstKind Kind = Inst::Call;
     return new (Func->allocate<InstCall>()) InstCall(
@@ -404,7 +404,7 @@ private:
   bool HasTailCall;
 };
 
-// Cast instruction (a.k.a. conversion operation).
+/// Cast instruction (a.k.a. conversion operation).
 class InstCast : public InstHighLevel {
   InstCast() = delete;
   InstCast(const InstCast &) = delete;
@@ -435,7 +435,7 @@ private:
   const OpKind CastKind;
 };
 
-// ExtractElement instruction.
+/// ExtractElement instruction.
 class InstExtractElement : public InstHighLevel {
   InstExtractElement() = delete;
   InstExtractElement(const InstExtractElement &) = delete;
@@ -458,8 +458,8 @@ private:
                      Operand *Source2);
 };
 
-// Floating-point comparison instruction.  The source operands are
-// captured in getSrc(0) and getSrc(1).
+/// Floating-point comparison instruction.  The source operands are
+/// captured in getSrc(0) and getSrc(1).
 class InstFcmp : public InstHighLevel {
   InstFcmp() = delete;
   InstFcmp(const InstFcmp &) = delete;
@@ -489,8 +489,8 @@ private:
   const FCond Condition;
 };
 
-// Integer comparison instruction.  The source operands are captured
-// in getSrc(0) and getSrc(1).
+/// Integer comparison instruction.  The source operands are captured
+/// in getSrc(0) and getSrc(1).
 class InstIcmp : public InstHighLevel {
   InstIcmp() = delete;
   InstIcmp(const InstIcmp &) = delete;
@@ -520,7 +520,7 @@ private:
   const ICond Condition;
 };
 
-// InsertElement instruction.
+/// InsertElement instruction.
 class InstInsertElement : public InstHighLevel {
   InstInsertElement() = delete;
   InstInsertElement(const InstInsertElement &) = delete;
@@ -543,8 +543,8 @@ private:
                     Operand *Source2, Operand *Source3);
 };
 
-// Call to an intrinsic function.  The call target is captured as getSrc(0),
-// and arg I is captured as getSrc(I+1).
+/// Call to an intrinsic function.  The call target is captured as getSrc(0),
+/// and arg I is captured as getSrc(I+1).
 class InstIntrinsicCall : public InstCall {
   InstIntrinsicCall() = delete;
   InstIntrinsicCall(const InstIntrinsicCall &) = delete;
@@ -573,7 +573,7 @@ private:
   const Intrinsics::IntrinsicInfo Info;
 };
 
-// Load instruction.  The source address is captured in getSrc(0).
+/// Load instruction.  The source address is captured in getSrc(0).
 class InstLoad : public InstHighLevel {
   InstLoad() = delete;
   InstLoad(const InstLoad &) = delete;
@@ -594,8 +594,8 @@ private:
   InstLoad(Cfg *Func, Variable *Dest, Operand *SourceAddr);
 };
 
-// Phi instruction.  For incoming edge I, the node is Labels[I] and
-// the Phi source operand is getSrc(I).
+/// Phi instruction.  For incoming edge I, the node is Labels[I] and
+/// the Phi source operand is getSrc(I).
 class InstPhi : public InstHighLevel {
   InstPhi() = delete;
   InstPhi(const InstPhi &) = delete;
@@ -621,15 +621,15 @@ private:
     Inst::destroy(Func);
   }
 
-  // Labels[] duplicates the InEdges[] information in the enclosing
-  // CfgNode, but the Phi instruction is created before InEdges[]
-  // is available, so it's more complicated to share the list.
+  /// Labels[] duplicates the InEdges[] information in the enclosing
+  /// CfgNode, but the Phi instruction is created before InEdges[]
+  /// is available, so it's more complicated to share the list.
   CfgNode **Labels;
 };
 
-// Ret instruction.  The return value is captured in getSrc(0), but if
-// there is no return value (void-type function), then
-// getSrcSize()==0 and hasRetValue()==false.
+/// Ret instruction.  The return value is captured in getSrc(0), but if
+/// there is no return value (void-type function), then
+/// getSrcSize()==0 and hasRetValue()==false.
 class InstRet : public InstHighLevel {
   InstRet() = delete;
   InstRet(const InstRet &) = delete;
@@ -652,7 +652,7 @@ private:
   InstRet(Cfg *Func, Operand *RetValue);
 };
 
-// Select instruction.  The condition, true, and false operands are captured.
+/// Select instruction.  The condition, true, and false operands are captured.
 class InstSelect : public InstHighLevel {
   InstSelect() = delete;
   InstSelect(const InstSelect &) = delete;
@@ -675,8 +675,8 @@ private:
              Operand *Source2);
 };
 
-// Store instruction.  The address operand is captured, along with the
-// data operand to be stored into the address.
+/// Store instruction.  The address operand is captured, along with the
+/// data operand to be stored into the address.
 class InstStore : public InstHighLevel {
   InstStore() = delete;
   InstStore(const InstStore &) = delete;
@@ -700,8 +700,8 @@ private:
   InstStore(Cfg *Func, Operand *Data, Operand *Addr);
 };
 
-// Switch instruction.  The single source operand is captured as
-// getSrc(0).
+/// Switch instruction.  The single source operand is captured as
+/// getSrc(0).
 class InstSwitch : public InstHighLevel {
   InstSwitch() = delete;
   InstSwitch(const InstSwitch &) = delete;
@@ -739,13 +739,13 @@ private:
   }
 
   CfgNode *LabelDefault;
-  SizeT NumCases;   // not including the default case
-  uint64_t *Values; // size is NumCases
-  CfgNode **Labels; // size is NumCases
+  SizeT NumCases;   /// not including the default case
+  uint64_t *Values; /// size is NumCases
+  CfgNode **Labels; /// size is NumCases
 };
 
-// Unreachable instruction.  This is a terminator instruction with no
-// operands.
+/// Unreachable instruction.  This is a terminator instruction with no
+/// operands.
 class InstUnreachable : public InstHighLevel {
   InstUnreachable() = delete;
   InstUnreachable(const InstUnreachable &) = delete;
@@ -765,8 +765,8 @@ private:
   explicit InstUnreachable(Cfg *Func);
 };
 
-// BundleLock instruction.  There are no operands.  Contains an option
-// indicating whether align_to_end is specified.
+/// BundleLock instruction.  There are no operands.  Contains an option
+/// indicating whether align_to_end is specified.
 class InstBundleLock : public InstHighLevel {
   InstBundleLock() = delete;
   InstBundleLock(const InstBundleLock &) = delete;
@@ -791,7 +791,7 @@ private:
   InstBundleLock(Cfg *Func, Option BundleOption);
 };
 
-// BundleUnlock instruction.  There are no operands.
+/// BundleUnlock instruction.  There are no operands.
 class InstBundleUnlock : public InstHighLevel {
   InstBundleUnlock() = delete;
   InstBundleUnlock(const InstBundleUnlock &) = delete;
@@ -812,18 +812,18 @@ private:
   explicit InstBundleUnlock(Cfg *Func);
 };
 
-// FakeDef instruction.  This creates a fake definition of a variable,
-// which is how we represent the case when an instruction produces
-// multiple results.  This doesn't happen with high-level ICE
-// instructions, but might with lowered instructions.  For example,
-// this would be a way to represent condition flags being modified by
-// an instruction.
-//
-// It's generally useful to set the optional source operand to be the
-// dest variable of the instruction that actually produces the FakeDef
-// dest.  Otherwise, the original instruction could be dead-code
-// eliminated if its dest operand is unused, and therefore the FakeDef
-// dest wouldn't be properly initialized.
+/// FakeDef instruction.  This creates a fake definition of a variable,
+/// which is how we represent the case when an instruction produces
+/// multiple results.  This doesn't happen with high-level ICE
+/// instructions, but might with lowered instructions.  For example,
+/// this would be a way to represent condition flags being modified by
+/// an instruction.
+///
+/// It's generally useful to set the optional source operand to be the
+/// dest variable of the instruction that actually produces the FakeDef
+/// dest.  Otherwise, the original instruction could be dead-code
+/// eliminated if its dest operand is unused, and therefore the FakeDef
+/// dest wouldn't be properly initialized.
 class InstFakeDef : public InstHighLevel {
   InstFakeDef() = delete;
   InstFakeDef(const InstFakeDef &) = delete;
@@ -843,11 +843,11 @@ private:
   InstFakeDef(Cfg *Func, Variable *Dest, Variable *Src);
 };
 
-// FakeUse instruction.  This creates a fake use of a variable, to
-// keep the instruction that produces that variable from being
-// dead-code eliminated.  This is useful in a variety of lowering
-// situations.  The FakeUse instruction has no dest, so it can itself
-// never be dead-code eliminated.
+/// FakeUse instruction.  This creates a fake use of a variable, to
+/// keep the instruction that produces that variable from being
+/// dead-code eliminated.  This is useful in a variety of lowering
+/// situations.  The FakeUse instruction has no dest, so it can itself
+/// never be dead-code eliminated.
 class InstFakeUse : public InstHighLevel {
   InstFakeUse() = delete;
   InstFakeUse(const InstFakeUse &) = delete;
@@ -866,16 +866,16 @@ private:
   InstFakeUse(Cfg *Func, Variable *Src);
 };
 
-// FakeKill instruction.  This "kills" a set of variables by modeling
-// a trivial live range at this instruction for each (implicit)
-// variable.  The primary use is to indicate that scratch registers
-// are killed after a call, so that the register allocator won't
-// assign a scratch register to a variable whose live range spans a
-// call.
-//
-// The FakeKill instruction also holds a pointer to the instruction
-// that kills the set of variables, so that if that linked instruction
-// gets dead-code eliminated, the FakeKill instruction will as well.
+/// FakeKill instruction.  This "kills" a set of variables by modeling
+/// a trivial live range at this instruction for each (implicit)
+/// variable.  The primary use is to indicate that scratch registers
+/// are killed after a call, so that the register allocator won't
+/// assign a scratch register to a variable whose live range spans a
+/// call.
+///
+/// The FakeKill instruction also holds a pointer to the instruction
+/// that kills the set of variables, so that if that linked instruction
+/// gets dead-code eliminated, the FakeKill instruction will as well.
 class InstFakeKill : public InstHighLevel {
   InstFakeKill() = delete;
   InstFakeKill(const InstFakeKill &) = delete;
@@ -894,12 +894,12 @@ public:
 private:
   InstFakeKill(Cfg *Func, const Inst *Linked);
 
-  // This instruction is ignored if Linked->isDeleted() is true.
+  /// This instruction is ignored if Linked->isDeleted() is true.
   const Inst *Linked;
 };
 
-// The Target instruction is the base class for all target-specific
-// instructions.
+/// The Target instruction is the base class for all target-specific
+/// instructions.
 class InstTarget : public Inst {
   InstTarget() = delete;
   InstTarget(const InstTarget &) = delete;
@@ -923,8 +923,8 @@ bool checkForRedundantAssign(const Variable *Dest, const Operand *Source);
 
 namespace llvm {
 
-// Override the default ilist traits so that Inst's private ctor and
-// deleted dtor aren't invoked.
+/// Override the default ilist traits so that Inst's private ctor and
+/// deleted dtor aren't invoked.
 template <>
 struct ilist_traits<Ice::Inst> : public ilist_default_traits<Ice::Inst> {
   Ice::Inst *createSentinel() const {