IR: Cleanup comments for Value, User, and MDNode

A follow-up commit will modify the memory-layout of `Value`, `User`, and
`MDNode`.  First fix the comments to be doxygen-friendly (and to follow
the coding standards).

  - Use "\brief" instead of "repeatedName -".
  - Add a brief intro where it was missing.
  - Remove duplicated comments from source files (and a couple of
    noisy/trivial comments altogether).

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@219844 91177308-0d34-0410-b5e6-96231b3b80d8

include/llvm/IR/Metadata.h

@@ -35,7 +35,8 @@ enum LLVMConstants : uint32_t {
 };
 
 //===----------------------------------------------------------------------===//
-/// MDString - a single uniqued string.
+/// \brief A single uniqued string.
+///
 /// These are used to efficiently contain a byte sequence for metadata.
 /// MDString is always unnamed.
 class MDString : public Value {
@@ -55,19 +56,19 @@ public:
 
   typedef StringRef::iterator iterator;
 
-  /// begin() - Pointer to the first byte of the string.
+  /// \brief Pointer to the first byte of the string.
   iterator begin() const { return getName().begin(); }
 
-  /// end() - Pointer to one byte past the end of the string.
+  /// \brief Pointer to one byte past the end of the string.
   iterator end() const { return getName().end(); }
 
-  /// Methods for support type inquiry through isa, cast, and dyn_cast:
+  /// \brief Methods for support type inquiry through isa, cast, and dyn_cast.
   static bool classof(const Value *V) {
     return V->getValueID() == MDStringVal;
   }
 };
 
-/// AAMDNodes - A collection of metadata nodes that might be associated with a
+/// \brief A collection of metadata nodes that might be associated with a
 /// memory access used by the alias-analysis infrastructure.
 struct AAMDNodes {
   explicit AAMDNodes(MDNode *T = nullptr, MDNode *S = nullptr,
@@ -82,13 +83,13 @@ struct AAMDNodes {
 
   LLVM_EXPLICIT operator bool() const { return TBAA || Scope || NoAlias; }
 
-  /// TBAA - The tag for type-based alias analysis.
+  /// \brief The tag for type-based alias analysis.
   MDNode *TBAA;
 
-  /// Scope - The tag for alias scope specification (used with noalias).
+  /// \brief The tag for alias scope specification (used with noalias).
   MDNode *Scope;
 
-  /// NoAlias - The tag specifying the noalias scope.
+  /// \brief The tag specifying the noalias scope.
   MDNode *NoAlias;
 };
 
@@ -114,7 +115,7 @@ struct DenseMapInfo<AAMDNodes> {
 class MDNodeOperand;
 
 //===----------------------------------------------------------------------===//
-/// MDNode - a tuple of other values.
+/// \brief A tuple of other values.
 class MDNode : public Value, public FoldingSetNode {
   MDNode(const MDNode &) LLVM_DELETED_FUNCTION;
   void operator=(const MDNode &) LLVM_DELETED_FUNCTION;
@@ -122,14 +123,13 @@ class MDNode : public Value, public FoldingSetNode {
   friend class LLVMContextImpl;
   friend struct FoldingSetTrait<MDNode>;
 
-  /// Hash - If the MDNode is uniqued cache the hash to speed up lookup.
+  /// \brief If the MDNode is uniqued cache the hash to speed up lookup.
   unsigned Hash;
 
-  /// NumOperands - This many 'MDNodeOperand' items are co-allocated onto the
+  /// \brief Number of co-allocated 'MDNodeOperand' items.
-  /// end of this MDNode.
   unsigned NumOperands;
 
-  // Subclass data enums.
+  /// \brief Subclass data enums.
   enum {
     /// FunctionLocalBit - This bit is set if this MDNode is function local.
     /// This is true when it (potentially transitively) contains a reference to
@@ -145,15 +145,14 @@ class MDNode : public Value, public FoldingSetNode {
     DestroyFlag      = 1 << 2
   };
 
-  // FunctionLocal enums.
+  /// \brief FunctionLocal enums.
   enum FunctionLocalness {
     FL_Unknown = -1,
     FL_No = 0,
     FL_Yes = 1
   };
 
-  /// replaceOperand - Replace each instance of F from the operand list of this
+  /// \brief Replace each instance of the given operand with a new value.
-  /// node with T.
   void replaceOperand(MDNodeOperand *Op, Value *NewVal);
   ~MDNode();
 
@@ -162,58 +161,62 @@ class MDNode : public Value, public FoldingSetNode {
   static MDNode *getMDNode(LLVMContext &C, ArrayRef<Value*> Vals,
                            FunctionLocalness FL, bool Insert = true);
 public:
-  // Constructors and destructors.
   static MDNode *get(LLVMContext &Context, ArrayRef<Value*> Vals);
-  // getWhenValsUnresolved - Construct MDNode determining function-localness
+  /// \brief Construct MDNode with an explicit function-localness.
-  // from isFunctionLocal argument, not by analyzing Vals.
+  ///
+  /// Don't analyze Vals; trust isFunctionLocal.
   static MDNode *getWhenValsUnresolved(LLVMContext &Context,
                                        ArrayRef<Value*> Vals,
                                        bool isFunctionLocal);
 
   static MDNode *getIfExists(LLVMContext &Context, ArrayRef<Value*> Vals);
 
-  /// getTemporary - Return a temporary MDNode, for use in constructing
+  /// \brief Return a temporary MDNode
-  /// cyclic MDNode structures. A temporary MDNode is not uniqued,
+  ///
-  /// may be RAUW'd, and must be manually deleted with deleteTemporary.
+  /// For use in constructing cyclic MDNode structures. A temporary MDNode is
+  /// not uniqued, may be RAUW'd, and must be manually deleted with
+  /// deleteTemporary.
   static MDNode *getTemporary(LLVMContext &Context, ArrayRef<Value*> Vals);
 
-  /// deleteTemporary - Deallocate a node created by getTemporary. The
+  /// \brief Deallocate a node created by getTemporary.
-  /// node must not have any users.
+  ///
+  /// The node must not have any users.
   static void deleteTemporary(MDNode *N);
 
-  /// replaceOperandWith - Replace a specific operand.
+  /// \brief Replace a specific operand.
   void replaceOperandWith(unsigned i, Value *NewVal);
 
-  /// getOperand - Return specified operand.
+  /// \brief Return specified operand.
   Value *getOperand(unsigned i) const LLVM_READONLY;
 
-  /// getNumOperands - Return number of MDNode operands.
+  /// \brief Return number of MDNode operands.
   unsigned getNumOperands() const { return NumOperands; }
 
-  /// isFunctionLocal - Return whether MDNode is local to a function.
+  /// \brief Return whether MDNode is local to a function.
   bool isFunctionLocal() const {
     return (getSubclassDataFromValue() & FunctionLocalBit) != 0;
   }
 
-  // getFunction - If this metadata is function-local and recursively has a
+  /// \brief Return the first function-local operand's function.
-  // function-local operand, return the first such operand's parent function.
+  ///
-  // Otherwise, return null. getFunction() should not be used for performance-
+  /// If this metadata is function-local and recursively has a function-local
-  // critical code because it recursively visits all the MDNode's operands.
+  /// operand, return the first such operand's parent function.  Otherwise,
+  /// return null. getFunction() should not be used for performance- critical
+  /// code because it recursively visits all the MDNode's operands.
   const Function *getFunction() const;
 
-  /// Profile - calculate a unique identifier for this MDNode to collapse
+  /// \brief Calculate a unique identifier for this MDNode.
-  /// duplicates
   void Profile(FoldingSetNodeID &ID) const;
 
-  /// Methods for support type inquiry through isa, cast, and dyn_cast:
+  /// \brief Methods for support type inquiry through isa, cast, and dyn_cast:
   static bool classof(const Value *V) {
     return V->getValueID() == MDNodeVal;
   }
 
-  /// Check whether MDNode is a vtable access.
+  /// \brief Check whether MDNode is a vtable access.
   bool isTBAAVtableAccess() const;
 
-  /// Methods for metadata merging.
+  /// \brief Methods for metadata merging.
   static MDNode *concatenate(MDNode *A, MDNode *B);
   static MDNode *intersect(MDNode *A, MDNode *B);
   static MDNode *getMostGenericTBAA(MDNode *A, MDNode *B);
@@ -221,7 +224,7 @@ public:
   static MDNode *getMostGenericFPMath(MDNode *A, MDNode *B);
   static MDNode *getMostGenericRange(MDNode *A, MDNode *B);
 private:
-  // destroy - Delete this node.  Only when there are no uses.
+  /// \brief Delete this node.  Only when there are no uses.
   void destroy();
 
   bool isNotUniqued() const {
@@ -237,9 +240,10 @@ private:
 };
 
 //===----------------------------------------------------------------------===//
-/// NamedMDNode - a tuple of MDNodes. Despite its name, a NamedMDNode isn't
+/// \brief A tuple of MDNodes.
-/// itself an MDNode. NamedMDNodes belong to modules, have names, and contain
+///
-/// lists of MDNodes.
+/// Despite its name, a NamedMDNode isn't itself an MDNode. NamedMDNodes belong
+/// to modules, have names, and contain lists of MDNodes.
 class NamedMDNode : public ilist_node<NamedMDNode> {
   friend class SymbolTableListTraits<NamedMDNode, Module>;
   friend struct ilist_traits<NamedMDNode>;
@@ -292,36 +296,23 @@ class NamedMDNode : public ilist_node<NamedMDNode> {
   };
 
 public:
-  /// eraseFromParent - Drop all references and remove the node from parent
+  /// \brief Drop all references and remove the node from parent module.
-  /// module.
   void eraseFromParent();
 
-  /// dropAllReferences - Remove all uses and clear node vector.
+  /// \brief Remove all uses and clear node vector.
   void dropAllReferences();
 
-  /// ~NamedMDNode - Destroy NamedMDNode.
   ~NamedMDNode();
 
-  /// getParent - Get the module that holds this named metadata collection.
+  /// \brief Get the module that holds this named metadata collection.
   inline Module *getParent() { return Parent; }
   inline const Module *getParent() const { return Parent; }
 
-  /// getOperand - Return specified operand.
   MDNode *getOperand(unsigned i) const;
-
-  /// getNumOperands - Return the number of NamedMDNode operands.
   unsigned getNumOperands() const;
-
-  /// addOperand - Add metadata operand.
   void addOperand(MDNode *M);
-
-  /// getName - Return a constant reference to this named metadata's name.
   StringRef getName() const;
-
-  /// print - Implement operator<< on NamedMDNode.
   void print(raw_ostream &ROS) const;
-
-  /// dump() - Allow printing of NamedMDNodes from the debugger.
   void dump() const;
 
   // ---------------------------------------------------------------------------

include/llvm/IR/User.h

@@ -26,9 +26,9 @@
 
 namespace llvm {
 
-/// OperandTraits - Compile-time customization of
+/// \brief Compile-time customization of User operands.
-/// operand-related allocators and accessors
+///
-/// for use of the User class
+/// Customizes operand-related allocators and accessors.
 template <class>
 struct OperandTraits;
 
@@ -39,11 +39,11 @@ class User : public Value {
   friend struct HungoffOperandTraits;
   virtual void anchor();
 protected:
-  /// NumOperands - The number of values used by this User.
+  /// \brief The number of values used by this User.
-  ///
   unsigned NumOperands;
 
-  /// OperandList - This is a pointer to the array of Uses for this User.
+  /// \brief This is a pointer to the array of Uses for this User.
+  ///
   /// For nodes of fixed arity (e.g. a binary operator) this array will live
   /// prefixed to some derived class instance.  For nodes of resizable variable
   /// arity (e.g. PHINodes, SwitchInst etc.), this memory will be dynamically
@@ -64,13 +64,13 @@ public:
   ~User() {
     Use::zap(OperandList, OperandList + NumOperands);
   }
-  /// operator delete - free memory allocated for User and Use objects
+  /// \brief Free memory allocated for User and Use objects.
   void operator delete(void *Usr);
-  /// placement delete - required by std, but never called.
+  /// \brief Placement delete - required by std, but never called.
   void operator delete(void*, unsigned) {
     llvm_unreachable("Constructor throws?");
   }
-  /// placement delete - required by std, but never called.
+  /// \brief Placement delete - required by std, but never called.
   void operator delete(void*, unsigned, bool) {
     llvm_unreachable("Constructor throws?");
   }
@@ -128,8 +128,7 @@ public:
     return const_op_range(op_begin(), op_end());
   }
 
-  /// Convenience iterator for directly iterating over the Values in the
+  /// \brief Iterator for directly iterating over the operand Values.
-  /// OperandList
   struct value_op_iterator
       : iterator_adaptor_base<value_op_iterator, op_iterator,
                               std::random_access_iterator_tag, Value *,
@@ -150,22 +149,23 @@ public:
     return iterator_range<value_op_iterator>(value_op_begin(), value_op_end());
   }
 
-  // dropAllReferences() - This function is in charge of "letting go" of all
+  /// \brief Drop all references to operands.
-  // objects that this User refers to.  This allows one to
+  ///
-  // 'delete' a whole class at a time, even though there may be circular
+  /// This function is in charge of "letting go" of all objects that this User
-  // references...  First all references are dropped, and all use counts go to
+  /// refers to.  This allows one to 'delete' a whole class at a time, even
-  // zero.  Then everything is deleted for real.  Note that no operations are
+  /// though there may be circular references...  First all references are
-  // valid on an object that has "dropped all references", except operator
+  /// dropped, and all use counts go to zero.  Then everything is deleted for
-  // delete.
+  /// real.  Note that no operations are valid on an object that has "dropped
-  //
+  /// all references", except operator delete.
   void dropAllReferences() {
     for (Use &U : operands())
       U.set(nullptr);
   }
 
-  /// replaceUsesOfWith - Replaces all references to the "From" definition with
+  /// \brief Replace uses of one Value with another.
-  /// references to the "To" definition.
   ///
+  /// Replaces all references to the "From" definition with references to the
+  /// "To" definition.
   void replaceUsesOfWith(Value *From, Value *To);
 
   // Methods for support type inquiry through isa, cast, and dyn_cast:

include/llvm/IR/Value.h

@@ -53,6 +53,8 @@ typedef StringMapEntry<Value*> ValueName;
 //                                 Value Class
 //===----------------------------------------------------------------------===//
 
+/// \brief LLVM Value Representation
+///
 /// This is a very important LLVM class. It is the base class of all values
 /// computed by a program that may be used as operands to other values. Value is
 /// the super class of other important classes such as Instruction and Function.
@@ -64,8 +66,6 @@ typedef StringMapEntry<Value*> ValueName;
 /// using this Value.  A Value can also have an arbitrary number of ValueHandle
 /// objects that watch it and listen to RAUW and Destroy events.  See
 /// llvm/IR/ValueHandle.h for details.
-///
-/// @brief LLVM Value Representation
 class Value {
   Type *VTy;
   Use *UseList;
@@ -77,16 +77,19 @@ class Value {
   const unsigned char SubclassID;   // Subclass identifier (for isa/dyn_cast)
   unsigned char HasValueHandle : 1; // Has a ValueHandle pointing to this?
 protected:
-  /// SubclassOptionalData - This member is similar to SubclassData, however it
+  /// \brief Hold subclass data that can be dropped.
-  /// is for holding information which may be used to aid optimization, but
+  ///
-  /// which may be cleared to zero without affecting conservative
+  /// This member is similar to SubclassData, however it is for holding
-  /// interpretation.
+  /// information which may be used to aid optimization, but which may be
+  /// cleared to zero without affecting conservative interpretation.
   unsigned char SubclassOptionalData : 7;
 
 private:
-  /// SubclassData - This member is defined by this class, but is not used for
+  /// \brief Hold arbitrary subclass data.
-  /// anything.  Subclasses can use it to hold whatever state they find useful.
+  ///
-  /// This field is initialized to zero by the ctor.
+  /// This member is defined by this class, but is not used for anything.
+  /// Subclasses can use it to hold whatever state they find useful.  This
+  /// field is initialized to zero by the ctor.
   unsigned short SubclassData;
 
   template <typename UseT> // UseT == 'Use' or 'const Use'
@@ -175,6 +178,7 @@ private:
     Use &getUse() const { return *UI; }
 
     /// \brief Return the operand # of this use in its User.
+    ///
     /// FIXME: Replace all callers with a direct call to Use::getOperandNo.
     unsigned getOperandNo() const { return UI->getOperandNo(); }
   };
@@ -187,15 +191,14 @@ protected:
 public:
   virtual ~Value();
 
-  /// dump - Support for debugging, callable in GDB: V->dump()
+  /// \brief Support for debugging, callable in GDB: V->dump()
-  //
   void dump() const;
 
-  /// print - Implement operator<< on Value.
+  /// \brief Implement operator<< on Value.
-  ///
   void print(raw_ostream &O) const;
 
   /// \brief Print the name of this Value out to the specified raw_ostream.
+  ///
   /// This is useful when you just want to print 'int %reg126', not the
   /// instruction that generated it. If you specify a Module for context, then
   /// even constanst get pretty-printed; for example, the type of a null
@@ -203,38 +206,43 @@ public:
   void printAsOperand(raw_ostream &O, bool PrintType = true,
                       const Module *M = nullptr) const;
 
-  /// All values are typed, get the type of this value.
+  /// \brief All values are typed, get the type of this value.
-  ///
   Type *getType() const { return VTy; }
 
-  /// All values hold a context through their type.
+  /// \brief All values hold a context through their type.
   LLVMContext &getContext() const;
 
-  // All values can potentially be named.
+  // \brief All values can potentially be named.
   bool hasName() const { return Name != nullptr && SubclassID != MDStringVal; }
   ValueName *getValueName() const { return Name; }
   void setValueName(ValueName *VN) { Name = VN; }
 
-  /// getName() - Return a constant reference to the value's name. This is cheap
+  /// \brief Return a constant reference to the value's name.
-  /// and guaranteed to return the same reference as long as the value is not
+  ///
-  /// modified.
+  /// This is cheap and guaranteed to return the same reference as long as the
+  /// value is not modified.
   StringRef getName() const;
 
-  /// setName() - Change the name of the value, choosing a new unique name if
+  /// \brief Change the name of the value.
-  /// the provided name is taken.
+  ///
+  /// Choose a new unique name if the provided name is taken.
   ///
   /// \param Name The new name; or "" if the value's name should be removed.
   void setName(const Twine &Name);
 
 
-  /// takeName - transfer the name from V to this value, setting V's name to
+  /// \brief Transfer the name from V to this value.
-  /// empty.  It is an error to call V->takeName(V).
+  ///
+  /// After taking V's name, sets V's name to empty.
+  ///
+  /// \note It is an error to call V->takeName(V).
   void takeName(Value *V);
 
-  /// replaceAllUsesWith - Go through the uses list for this definition and make
+  /// \brief Change all uses of this to point to a new Value.
-  /// each use point to "V" instead of "this".  After this completes, 'this's
-  /// use list is guaranteed to be empty.
   ///
+  /// Go through the uses list for this definition and make each use point to
+  /// "V" instead of "this".  After this completes, 'this's use list is
+  /// guaranteed to be empty.
   void replaceAllUsesWith(Value *V);
 
   //----------------------------------------------------------------------
@@ -270,36 +278,38 @@ public:
     return iterator_range<const_user_iterator>(user_begin(), user_end());
   }
 
-  /// hasOneUse - Return true if there is exactly one user of this value.  This
+  /// \brief Return true if there is exactly one user of this value.
-  /// is specialized because it is a common request and does not require
-  /// traversing the whole use list.
   ///
+  /// This is specialized because it is a common request and does not require
+  /// traversing the whole use list.
   bool hasOneUse() const {
     const_use_iterator I = use_begin(), E = use_end();
     if (I == E) return false;
     return ++I == E;
   }
 
-  /// hasNUses - Return true if this Value has exactly N users.
+  /// \brief Return true if this Value has exactly N users.
-  ///
   bool hasNUses(unsigned N) const;
 
-  /// hasNUsesOrMore - Return true if this value has N users or more.  This is
+  /// \brief Return true if this value has N users or more.
-  /// logically equivalent to getNumUses() >= N.
   ///
+  /// This is logically equivalent to getNumUses() >= N.
   bool hasNUsesOrMore(unsigned N) const;
 
+  /// \brief Check if this value is used in the specified basic block.
   bool isUsedInBasicBlock(const BasicBlock *BB) const;
 
-  /// getNumUses - This method computes the number of uses of this Value.  This
+  /// \brief This method computes the number of uses of this Value.
-  /// is a linear time operation.  Use hasOneUse, hasNUses, or hasNUsesOrMore
+  ///
-  /// to check for specific values.
+  /// This is a linear time operation.  Use hasOneUse, hasNUses, or
+  /// hasNUsesOrMore to check for specific values.
   unsigned getNumUses() const;
 
-  /// addUse - This method should only be used by the Use class.
+  /// \brief This method should only be used by the Use class.
-  ///
   void addUse(Use &U) { U.addToList(&UseList); }
 
+  /// \brief Concrete subclass of this.
+  ///
   /// An enumeration for keeping track of the concrete subclass of Value that
   /// is actually instantiated. Values of this enumeration are kept in the
   /// Value classes SubclassID field. They are used for concrete type
@@ -334,11 +344,12 @@ public:
     ConstantLastVal  = ConstantPointerNullVal
   };
 
-  /// getValueID - Return an ID for the concrete type of this object.  This is
+  /// \brief Return an ID for the concrete type of this object.
-  /// used to implement the classof checks.  This should not be used for any
+  ///
-  /// other purpose, as the values may change as LLVM evolves.  Also, note that
+  /// This is used to implement the classof checks.  This should not be used
-  /// for instructions, the Instruction's opcode is added to InstructionVal. So
+  /// for any other purpose, as the values may change as LLVM evolves.  Also,
-  /// this means three things:
+  /// note that for instructions, the Instruction's opcode is added to
+  /// InstructionVal. So this means three things:
   /// # there is no value with code InstructionVal (no opcode==0).
   /// # there are more possible values for the value type than in ValueTy enum.
   /// # the InstructionVal enumerator must be the highest valued enumerator in
@@ -347,64 +358,59 @@ public:
     return SubclassID;
   }
 
-  /// getRawSubclassOptionalData - Return the raw optional flags value
+  /// \brief Return the raw optional flags value contained in this value.
-  /// contained in this value. This should only be used when testing two
+  ///
-  /// Values for equivalence.
+  /// This should only be used when testing two Values for equivalence.
   unsigned getRawSubclassOptionalData() const {
     return SubclassOptionalData;
   }
 
-  /// clearSubclassOptionalData - Clear the optional flags contained in
+  /// \brief Clear the optional flags contained in this value.
-  /// this value.
   void clearSubclassOptionalData() {
     SubclassOptionalData = 0;
   }
 
-  /// hasSameSubclassOptionalData - Test whether the optional flags contained
+  /// \brief Check the optional flags for equality.
-  /// in this value are equal to the optional flags in the given value.
   bool hasSameSubclassOptionalData(const Value *V) const {
     return SubclassOptionalData == V->SubclassOptionalData;
   }
 
-  /// intersectOptionalDataWith - Clear any optional flags in this value
+  /// \brief Clear any optional flags not set in the given Value.
-  /// that are not also set in the given value.
   void intersectOptionalDataWith(const Value *V) {
     SubclassOptionalData &= V->SubclassOptionalData;
   }
 
-  /// hasValueHandle - Return true if there is a value handle associated with
+  /// \brief Return true if there is a value handle associated with this value.
-  /// this value.
   bool hasValueHandle() const { return HasValueHandle; }
 
-  /// \brief Strips off any unneeded pointer casts, all-zero GEPs and aliases
+  /// \brief Strip off pointer casts, all-zero GEPs, and aliases.
-  /// from the specified value, returning the original uncasted value.
   ///
-  /// If this is called on a non-pointer value, it returns 'this'.
+  /// Returns the original uncasted value.  If this is called on a non-pointer
+  /// value, it returns 'this'.
   Value *stripPointerCasts();
   const Value *stripPointerCasts() const {
     return const_cast<Value*>(this)->stripPointerCasts();
   }
 
-  /// \brief Strips off any unneeded pointer casts and all-zero GEPs from the
+  /// \brief Strip off pointer casts and all-zero GEPs.
-  /// specified value, returning the original uncasted value.
   ///
-  /// If this is called on a non-pointer value, it returns 'this'.
+  /// Returns the original uncasted value.  If this is called on a non-pointer
+  /// value, it returns 'this'.
   Value *stripPointerCastsNoFollowAliases();
   const Value *stripPointerCastsNoFollowAliases() const {
     return const_cast<Value*>(this)->stripPointerCastsNoFollowAliases();
   }
 
-  /// \brief Strips off unneeded pointer casts and all-constant GEPs from the
+  /// \brief Strip off pointer casts and all-constant inbounds GEPs.
-  /// specified value, returning the original pointer value.
   ///
-  /// If this is called on a non-pointer value, it returns 'this'.
+  /// Returns the original pointer value.  If this is called on a non-pointer
+  /// value, it returns 'this'.
   Value *stripInBoundsConstantOffsets();
   const Value *stripInBoundsConstantOffsets() const {
     return const_cast<Value*>(this)->stripInBoundsConstantOffsets();
   }
 
-  /// \brief Strips like \c stripInBoundsConstantOffsets but also accumulates
+  /// \brief Accumulate offsets from \a stripInBoundsConstantOffsets().
-  /// the constant offset stripped.
   ///
   /// Stores the resulting constant offset stripped into the APInt provided.
   /// The provided APInt will be extended or truncated as needed to be the
@@ -419,23 +425,27 @@ public:
         ->stripAndAccumulateInBoundsConstantOffsets(DL, Offset);
   }
 
-  /// \brief Strips off unneeded pointer casts and any in-bounds offsets from
+  /// \brief Strip off pointer casts and inbounds GEPs.
-  /// the specified value, returning the original pointer value.
   ///
-  /// If this is called on a non-pointer value, it returns 'this'.
+  /// Returns the original pointer value.  If this is called on a non-pointer
+  /// value, it returns 'this'.
   Value *stripInBoundsOffsets();
   const Value *stripInBoundsOffsets() const {
     return const_cast<Value*>(this)->stripInBoundsOffsets();
   }
 
-  /// isDereferenceablePointer - Test if this value is always a pointer to
+  /// \brief Check if this is always a dereferenceable pointer.
-  /// allocated and suitably aligned memory for a simple load or store.
+  ///
+  /// Test if this value is always a pointer to allocated and suitably aligned
+  /// memory for a simple load or store.
   bool isDereferenceablePointer(const DataLayout *DL = nullptr) const;
 
-  /// DoPHITranslation - If this value is a PHI node with CurBB as its parent,
+  /// \brief Translate PHI node to its predecessor from the given basic block.
-  /// return the value in the PHI node corresponding to PredBB.  If not, return
+  ///
-  /// ourself.  This is useful if you want to know the value something has in a
+  /// If this value is a PHI node with CurBB as its parent, return the value in
-  /// predecessor block.
+  /// the PHI node corresponding to PredBB.  If not, return ourself.  This is
+  /// useful if you want to know the value something has in a predecessor
+  /// block.
   Value *DoPHITranslation(const BasicBlock *CurBB, const BasicBlock *PredBB);
 
   const Value *DoPHITranslation(const BasicBlock *CurBB,
@@ -443,11 +453,14 @@ public:
     return const_cast<Value*>(this)->DoPHITranslation(CurBB, PredBB);
   }
 
-  /// MaximumAlignment - This is the greatest alignment value supported by
+  /// \brief The maximum alignment for instructions.
-  /// load, store, and alloca instructions, and global values.
+  ///
+  /// This is the greatest alignment value supported by load, store, and alloca
+  /// instructions, and global values.
   static const unsigned MaximumAlignment = 1u << 29;
 
-  /// mutateType - Mutate the type of this Value to be of the specified type.
+  /// \brief Mutate the type of this Value to be of the specified type.
+  ///
   /// Note that this is an extremely dangerous operation which can create
   /// completely invalid IR very easily.  It is strongly recommended that you
   /// recreate IR objects with the right types instead of mutating them in

include/llvm/IR/ValueHandle.h

@@ -33,15 +33,16 @@ public:
   enum { NumLowBitsAvailable = 2 };
 };
 
-/// ValueHandleBase - This is the common base class of value handles.
+/// \brief This is the common base class of value handles.
+///
 /// ValueHandle's are smart pointers to Value's that have special behavior when
 /// the value is deleted or ReplaceAllUsesWith'd.  See the specific handles
 /// below for details.
-///
 class ValueHandleBase {
   friend class Value;
 protected:
-  /// HandleBaseKind - This indicates what sub class the handle actually is.
+  /// \brief This indicates what sub class the handle actually is.
+  ///
   /// This is to avoid having a vtable for the light-weight handle pointers. The
   /// fully general Callback version does have a vtable.
   enum HandleBaseKind {
@@ -122,26 +123,28 @@ private:
   HandleBaseKind getKind() const { return PrevPair.getInt(); }
   void setPrevPtr(ValueHandleBase **Ptr) { PrevPair.setPointer(Ptr); }
 
-  /// AddToExistingUseList - Add this ValueHandle to the use list for VP, where
+  /// \brief Add this ValueHandle to the use list for VP.
+  ///
   /// List is the address of either the head of the list or a Next node within
   /// the existing use list.
   void AddToExistingUseList(ValueHandleBase **List);
 
-  /// AddToExistingUseListAfter - Add this ValueHandle to the use list after
+  /// \brief Add this ValueHandle to the use list after Node.
-  /// Node.
   void AddToExistingUseListAfter(ValueHandleBase *Node);
 
-  /// AddToUseList - Add this ValueHandle to the use list for VP.
+  /// \brief Add this ValueHandle to the use list for VP.
   void AddToUseList();
-  /// RemoveFromUseList - Remove this ValueHandle from its current use list.
+  /// \brief Remove this ValueHandle from its current use list.
   void RemoveFromUseList();
 };
 
-/// WeakVH - This is a value handle that tries hard to point to a Value, even
+/// \brief Value handle that is nullable, but tries to track the Value.
-/// across RAUW operations, but will null itself out if the value is destroyed.
+///
-/// this is useful for advisory sorts of information, but should not be used as
+/// This is a value handle that tries hard to point to a Value, even across
-/// the key of a map (since the map would have to rearrange itself when the
+/// RAUW operations, but will null itself out if the value is destroyed.  this
-/// pointer changes).
+/// is useful for advisory sorts of information, but should not be used as the
+/// key of a map (since the map would have to rearrange itself when the pointer
+/// changes).
 class WeakVH : public ValueHandleBase {
 public:
   WeakVH() : ValueHandleBase(Weak) {}
@@ -170,14 +173,16 @@ template<> struct simplify_type<WeakVH> {
   }
 };
 
-/// AssertingVH - This is a Value Handle that points to a value and asserts out
+/// \brief Value handle that asserts if the Value is deleted.
-/// if the value is destroyed while the handle is still live.  This is very
+///
-/// useful for catching dangling pointer bugs and other things which can be
+/// This is a Value Handle that points to a value and asserts out if the value
-/// non-obvious.  One particularly useful place to use this is as the Key of a
+/// is destroyed while the handle is still live.  This is very useful for
-/// map.  Dangling pointer bugs often lead to really subtle bugs that only occur
+/// catching dangling pointer bugs and other things which can be non-obvious.
-/// if another object happens to get allocated to the same address as the old
+/// One particularly useful place to use this is as the Key of a map.  Dangling
-/// one.  Using an AssertingVH ensures that an assert is triggered as soon as
+/// pointer bugs often lead to really subtle bugs that only occur if another
-/// the bad delete occurs.
+/// object happens to get allocated to the same address as the old one.  Using
+/// an AssertingVH ensures that an assert is triggered as soon as the bad
+/// delete occurs.
 ///
 /// Note that an AssertingVH handle does *not* follow values across RAUW
 /// operations.  This means that RAUW's need to explicitly update the
@@ -272,8 +277,7 @@ struct isPodLike<AssertingVH<T> > {
 };
 
 
-/// TrackingVH - This is a value handle that tracks a Value (or Value subclass),
+/// \brief Value handle that tracks a Value across RAUW.
-/// even across RAUW operations.
 ///
 /// TrackingVH is designed for situations where a client needs to hold a handle
 /// to a Value (or subclass) across some operations which may move that value,
@@ -341,12 +345,14 @@ public:
   ValueTy &operator*() const { return *getValPtr(); }
 };
 
-/// CallbackVH - This is a value handle that allows subclasses to define
+/// \brief Value handle with callbacks on RAUW and destruction.
-/// callbacks that run when the underlying Value has RAUW called on it or is
+///
-/// destroyed.  This class can be used as the key of a map, as long as the user
+/// This is a value handle that allows subclasses to define callbacks that run
-/// takes it out of the map before calling setValPtr() (since the map has to
+/// when the underlying Value has RAUW called on it or is destroyed.  This
-/// rearrange itself when the pointer changes).  Unlike ValueHandleBase, this
+/// class can be used as the key of a map, as long as the user takes it out of
-/// class has a vtable and a virtual destructor.
+/// the map before calling setValPtr() (since the map has to rearrange itself
+/// when the pointer changes).  Unlike ValueHandleBase, this class has a vtable
+/// and a virtual destructor.
 class CallbackVH : public ValueHandleBase {
   virtual void anchor();
 protected:
@@ -367,16 +373,20 @@ public:
     return getValPtr();
   }
 
-  /// Called when this->getValPtr() is destroyed, inside ~Value(), so you may
+  /// \brief Callback for Value destruction.
-  /// call any non-virtual Value method on getValPtr(), but no subclass methods.
+  ///
-  /// If WeakVH were implemented as a CallbackVH, it would use this method to
+  /// Called when this->getValPtr() is destroyed, inside ~Value(), so you
-  /// call setValPtr(NULL).  AssertingVH would use this method to cause an
+  /// may call any non-virtual Value method on getValPtr(), but no subclass
-  /// assertion failure.
+  /// methods.  If WeakVH were implemented as a CallbackVH, it would use this
+  /// method to call setValPtr(NULL).  AssertingVH would use this method to
+  /// cause an assertion failure.
   ///
   /// All implementations must remove the reference from this object to the
   /// Value that's being destroyed.
   virtual void deleted() { setValPtr(nullptr); }
 
+  /// \brief Callback for Value RAUW.
+  ///
   /// Called when this->getValPtr()->replaceAllUsesWith(new_value) is called,
   /// _before_ any of the uses have actually been replaced.  If WeakVH were
   /// implemented as a CallbackVH, it would use this method to call

lib/IR/Metadata.cpp

@@ -74,8 +74,7 @@ public:
     this->setAsFirstOperand(IsFirst);
   }
 
-  /// setAsFirstOperand - Accessor method to mark the operand as the first in
+  /// \brief Accessor method to mark the operand as the first in the list.
-  /// the list.
   void setAsFirstOperand(unsigned V) { this->setValPtrInt(V); }
 
   void deleted() override;
@@ -98,8 +97,7 @@ void MDNodeOperand::allUsesReplacedWith(Value *NV) {
 // MDNode implementation.
 //
 
-/// getOperandPtr - Helper function to get the MDNodeOperand's coallocated on
+/// \brief Get the MDNodeOperand's coallocated on the end of the MDNode.
-/// the end of the MDNode.
 static MDNodeOperand *getOperandPtr(MDNode *N, unsigned Op) {
   // Use <= instead of < to permit a one-past-the-end address.
   assert(Op <= N->getNumOperands() && "Invalid operand number");
@@ -209,8 +207,7 @@ void MDNode::destroy() {
   free(this);
 }
 
-/// isFunctionLocalValue - Return true if this is a value that would require a
+/// \brief Check if the Value  would require a function-local MDNode.
-/// function-local MDNode.
 static bool isFunctionLocalValue(Value *V) {
   return isa<Instruction>(V) || isa<Argument>(V) || isa<BasicBlock>(V) ||
          (isa<MDNode>(V) && cast<MDNode>(V)->isFunctionLocal());
@@ -304,7 +301,7 @@ void MDNode::deleteTemporary(MDNode *N) {
   N->destroy();
 }
 
-/// getOperand - Return specified operand.
+/// \brief Return specified operand.
 Value *MDNode::getOperand(unsigned i) const {
   assert(i < getNumOperands() && "Invalid operand number");
   return *getOperandPtr(const_cast<MDNode*>(this), i);
@@ -572,36 +569,29 @@ NamedMDNode::~NamedMDNode() {
   delete &getNMDOps(Operands);
 }
 
-/// getNumOperands - Return number of NamedMDNode operands.
 unsigned NamedMDNode::getNumOperands() const {
   return (unsigned)getNMDOps(Operands).size();
 }
 
-/// getOperand - Return specified operand.
 MDNode *NamedMDNode::getOperand(unsigned i) const {
   assert(i < getNumOperands() && "Invalid Operand number!");
   return dyn_cast<MDNode>(&*getNMDOps(Operands)[i]);
 }
 
-/// addOperand - Add metadata Operand.
 void NamedMDNode::addOperand(MDNode *M) {
   assert(!M->isFunctionLocal() &&
          "NamedMDNode operands must not be function-local!");
   getNMDOps(Operands).push_back(TrackingVH<MDNode>(M));
 }
 
-/// eraseFromParent - Drop all references and remove the node from parent
-/// module.
 void NamedMDNode::eraseFromParent() {
   getParent()->eraseNamedMetadata(this);
 }
 
-/// dropAllReferences - Remove all uses and clear node vector.
 void NamedMDNode::dropAllReferences() {
   getNMDOps(Operands).clear();
 }
 
-/// getName - Return a constant reference to this named metadata's name.
 StringRef NamedMDNode::getName() const {
   return StringRef(Name);
 }

lib/IR/User.cpp

@@ -20,9 +20,6 @@ namespace llvm {
 
 void User::anchor() {}
 
-// replaceUsesOfWith - Replaces all references to the "From" definition with
-// references to the "To" definition.
-//
 void User::replaceUsesOfWith(Value *From, Value *To) {
   if (From == To) return;   // Duh what?
 

lib/IR/Value.cpp

@@ -88,8 +88,6 @@ Value::~Value() {
   LeakDetector::removeGarbageObject(this);
 }
 
-/// hasNUses - Return true if this Value has exactly N users.
-///
 bool Value::hasNUses(unsigned N) const {
   const_use_iterator UI = use_begin(), E = use_end();
 
@@ -98,9 +96,6 @@ bool Value::hasNUses(unsigned N) const {
   return UI == E;
 }
 
-/// hasNUsesOrMore - Return true if this value has N users or more.  This is
-/// logically equivalent to getNumUses() >= N.
-///
 bool Value::hasNUsesOrMore(unsigned N) const {
   const_use_iterator UI = use_begin(), E = use_end();
 
@@ -110,8 +105,6 @@ bool Value::hasNUsesOrMore(unsigned N) const {
   return true;
 }
 
-/// isUsedInBasicBlock - Return true if this value is used in the specified
-/// basic block.
 bool Value::isUsedInBasicBlock(const BasicBlock *BB) const {
   // This can be computed either by scanning the instructions in BB, or by
   // scanning the use list of this Value. Both lists can be very long, but
@@ -133,10 +126,6 @@ bool Value::isUsedInBasicBlock(const BasicBlock *BB) const {
   return false;
 }
 
-
-/// getNumUses - This method computes the number of uses of this Value.  This
-/// is a linear time operation.  Use hasOneUse or hasNUses to check for specific
-/// values.
 unsigned Value::getNumUses() const {
   return (unsigned)std::distance(use_begin(), use_end());
 }
@@ -236,9 +225,6 @@ void Value::setName(const Twine &NewName) {
   Name = ST->createValueName(NameRef, this);
 }
 
-
-/// takeName - transfer the name from V to this value, setting V's name to
-/// empty.  It is an error to call V->takeName(V).
 void Value::takeName(Value *V) {
   assert(SubclassID != MDStringVal && "Cannot take the name of an MDString!");
 
@@ -473,8 +459,10 @@ Value *Value::stripInBoundsOffsets() {
   return stripPointerCastsAndOffsets<PSK_InBounds>(this);
 }
 
-/// isDereferenceablePointer - Test if this value is always a pointer to
+/// \brief Check if Value is always a dereferenceable pointer.
-/// allocated and suitably aligned memory for a simple load or store.
+///
+/// Test if V is always a pointer to allocated and suitably aligned memory for
+/// a simple load or store.
 static bool isDereferenceablePointer(const Value *V, const DataLayout *DL,
                                      SmallPtrSetImpl<const Value *> &Visited) {
   // Note that it is not safe to speculate into a malloc'd region because
@@ -572,8 +560,6 @@ static bool isDereferenceablePointer(const Value *V, const DataLayout *DL,
   return false;
 }
 
-/// isDereferenceablePointer - Test if this value is always a pointer to
-/// allocated and suitably aligned memory for a simple load or store.
 bool Value::isDereferenceablePointer(const DataLayout *DL) const {
   // When dereferenceability information is provided by a dereferenceable
   // attribute, we know exactly how many bytes are dereferenceable. If we can
@@ -600,10 +586,6 @@ bool Value::isDereferenceablePointer(const DataLayout *DL) const {
   return ::isDereferenceablePointer(this, DL, Visited);
 }
 
-/// DoPHITranslation - If this value is a PHI node with CurBB as its parent,
-/// return the value in the PHI node corresponding to PredBB.  If not, return
-/// ourself.  This is useful if you want to know the value something has in a
-/// predecessor block.
 Value *Value::DoPHITranslation(const BasicBlock *CurBB,
                                const BasicBlock *PredBB) {
   PHINode *PN = dyn_cast<PHINode>(this);
@@ -637,8 +619,6 @@ void Value::reverseUseList() {
 //                             ValueHandleBase Class
 //===----------------------------------------------------------------------===//
 
-/// AddToExistingUseList - Add this ValueHandle to the use list for VP, where
-/// List is known to point into the existing use list.
 void ValueHandleBase::AddToExistingUseList(ValueHandleBase **List) {
   assert(List && "Handle list is null?");
 
@@ -662,7 +642,6 @@ void ValueHandleBase::AddToExistingUseListAfter(ValueHandleBase *List) {
     Next->setPrevPtr(&Next);
 }
 
-/// AddToUseList - Add this ValueHandle to the use list for VP.
 void ValueHandleBase::AddToUseList() {
   assert(VP.getPointer() && "Null pointer doesn't have a use list!");
 
@@ -706,7 +685,6 @@ void ValueHandleBase::AddToUseList() {
   }
 }
 
-/// RemoveFromUseList - Remove this ValueHandle from its current use list.
 void ValueHandleBase::RemoveFromUseList() {
   assert(VP.getPointer() && VP.getPointer()->HasValueHandle &&
          "Pointer doesn't have a use list!");