From: Duncan P. N. Exon Smith Date: Wed, 15 Oct 2014 20:28:31 +0000 (+0000) Subject: IR: Cleanup comments for Value, User, and MDNode X-Git-Url: http://plrg.eecs.uci.edu/git/?p=oota-llvm.git;a=commitdiff_plain;h=40dd9d68d717c286d78bfe804ce73602f64b8d72 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 --- diff --git a/include/llvm/IR/Metadata.h b/include/llvm/IR/Metadata.h index 9738be02c1e..8b33d7022c7 100644 --- a/include/llvm/IR/Metadata.h +++ b/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 { 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; - /// 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 - /// end of this MDNode. + /// \brief Number of co-allocated 'MDNodeOperand' items. 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 - /// node with T. + /// \brief Replace each instance of the given operand with a new value. void replaceOperand(MDNodeOperand *Op, Value *NewVal); ~MDNode(); @@ -162,58 +161,62 @@ class MDNode : public Value, public FoldingSetNode { static MDNode *getMDNode(LLVMContext &C, ArrayRef Vals, FunctionLocalness FL, bool Insert = true); public: - // Constructors and destructors. static MDNode *get(LLVMContext &Context, ArrayRef Vals); - // getWhenValsUnresolved - Construct MDNode determining function-localness - // from isFunctionLocal argument, not by analyzing Vals. + /// \brief Construct MDNode with an explicit function-localness. + /// + /// Don't analyze Vals; trust isFunctionLocal. static MDNode *getWhenValsUnresolved(LLVMContext &Context, ArrayRef Vals, bool isFunctionLocal); static MDNode *getIfExists(LLVMContext &Context, ArrayRef Vals); - /// getTemporary - Return a temporary MDNode, for use in constructing - /// cyclic MDNode structures. A temporary MDNode is not uniqued, - /// may be RAUW'd, and must be manually deleted with deleteTemporary. + /// \brief Return a temporary MDNode + /// + /// 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 Vals); - /// deleteTemporary - Deallocate a node created by getTemporary. The - /// node must not have any users. + /// \brief Deallocate a node created by getTemporary. + /// + /// 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 - // function-local 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. + /// \brief Return the first function-local operand's function. + /// + /// If this metadata is function-local and recursively has a function-local + /// 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 - /// duplicates + /// \brief Calculate a unique identifier for this MDNode. 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 -/// itself an MDNode. NamedMDNodes belong to modules, have names, and contain -/// lists of MDNodes. +/// \brief A tuple 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 { friend class SymbolTableListTraits; friend struct ilist_traits; @@ -292,36 +296,23 @@ class NamedMDNode : public ilist_node { }; public: - /// eraseFromParent - Drop all references and remove the node from parent - /// module. + /// \brief Drop all references and remove the node from parent 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; // --------------------------------------------------------------------------- diff --git a/include/llvm/IR/User.h b/include/llvm/IR/User.h index 848adae9cec..fb5abe0c0e4 100644 --- a/include/llvm/IR/User.h +++ b/include/llvm/IR/User.h @@ -26,9 +26,9 @@ namespace llvm { -/// OperandTraits - Compile-time customization of -/// operand-related allocators and accessors -/// for use of the User class +/// \brief Compile-time customization of User operands. +/// +/// Customizes operand-related allocators and accessors. template 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 - /// OperandList + /// \brief Iterator for directly iterating over the operand Values. struct value_op_iterator : iterator_adaptor_base(value_op_begin(), value_op_end()); } - // dropAllReferences() - This function is in charge of "letting go" of all - // objects that this User refers to. This allows one to - // 'delete' a whole class at a time, even though there may be circular - // references... First all references are dropped, and all use counts go to - // zero. Then everything is deleted for real. Note that no operations are - // valid on an object that has "dropped all references", except operator - // delete. - // + /// \brief Drop all references to operands. + /// + /// This function is in charge of "letting go" of all objects that this User + /// refers to. This allows one to 'delete' a whole class at a time, even + /// though there may be circular references... First all references are + /// dropped, and all use counts go to zero. Then everything is deleted for + /// 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 - /// references to the "To" definition. + /// \brief Replace uses of one Value with another. /// + /// 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: diff --git a/include/llvm/IR/Value.h b/include/llvm/IR/Value.h index 8850ffe3bee..02630d8c666 100644 --- a/include/llvm/IR/Value.h +++ b/include/llvm/IR/Value.h @@ -53,6 +53,8 @@ typedef StringMapEntry 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 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 - /// is for holding information which may be used to aid optimization, but - /// which may be cleared to zero without affecting conservative - /// interpretation. + /// \brief Hold subclass data that can be dropped. + /// + /// This member is similar to SubclassData, however it is for holding + /// 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 - /// anything. Subclasses can use it to hold whatever state they find useful. - /// This field is initialized to zero by the ctor. + /// \brief Hold arbitrary subclass data. + /// + /// 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 // 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 - /// and guaranteed to return the same reference as long as the value is not - /// modified. + /// \brief Return a constant reference to the value's name. + /// + /// 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 - /// the provided name is taken. + /// \brief Change the name of the value. + /// + /// 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 - /// empty. It is an error to call V->takeName(V). + /// \brief Transfer the name from V to this value. + /// + /// 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 - /// each use point to "V" instead of "this". After this completes, 'this's - /// use list is guaranteed to be empty. + /// \brief Change all uses of this to point to a new Value. /// + /// 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(user_begin(), user_end()); } - /// hasOneUse - Return true if there is exactly one user of this value. This - /// is specialized because it is a common request and does not require - /// traversing the whole use list. + /// \brief Return true if there is exactly one user of this value. /// + /// 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 - /// logically equivalent to getNumUses() >= N. + /// \brief Return true if this value has N users or more. /// + /// 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 - /// is a linear time operation. Use hasOneUse, hasNUses, or hasNUsesOrMore - /// to check for specific values. + /// \brief This method computes the number of uses of this Value. + /// + /// 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 - /// 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 - /// for instructions, the Instruction's opcode is added to InstructionVal. So - /// this means three things: + /// \brief Return an ID for the concrete type of this object. + /// + /// This is 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 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 - /// contained in this value. This should only be used when testing two - /// Values for equivalence. + /// \brief Return the raw optional flags value contained in this value. + /// + /// This should only be used when testing two Values for equivalence. unsigned getRawSubclassOptionalData() const { return SubclassOptionalData; } - /// clearSubclassOptionalData - Clear the optional flags contained in - /// this value. + /// \brief Clear the optional flags contained in this value. void clearSubclassOptionalData() { SubclassOptionalData = 0; } - /// hasSameSubclassOptionalData - Test whether the optional flags contained - /// in this value are equal to the optional flags in the given value. + /// \brief Check the optional flags for equality. bool hasSameSubclassOptionalData(const Value *V) const { return SubclassOptionalData == V->SubclassOptionalData; } - /// intersectOptionalDataWith - Clear any optional flags in this value - /// that are not also set in the given value. + /// \brief Clear any optional flags not set in the given Value. void intersectOptionalDataWith(const Value *V) { SubclassOptionalData &= V->SubclassOptionalData; } - /// hasValueHandle - Return true if there is a value handle associated with - /// this value. + /// \brief Return true if there is a value handle associated with this value. bool hasValueHandle() const { return HasValueHandle; } - /// \brief Strips off any unneeded pointer casts, all-zero GEPs and aliases - /// from the specified value, returning the original uncasted value. + /// \brief Strip off pointer casts, all-zero GEPs, and aliases. /// - /// 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(this)->stripPointerCasts(); } - /// \brief Strips off any unneeded pointer casts and all-zero GEPs from the - /// specified value, returning the original uncasted value. + /// \brief Strip off pointer casts and all-zero GEPs. /// - /// 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(this)->stripPointerCastsNoFollowAliases(); } - /// \brief Strips off unneeded pointer casts and all-constant GEPs from the - /// specified value, returning the original pointer value. + /// \brief Strip off pointer casts and all-constant inbounds GEPs. /// - /// 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(this)->stripInBoundsConstantOffsets(); } - /// \brief Strips like \c stripInBoundsConstantOffsets but also accumulates - /// the constant offset stripped. + /// \brief Accumulate offsets from \a stripInBoundsConstantOffsets(). /// /// 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 - /// the specified value, returning the original pointer value. + /// \brief Strip off pointer casts and inbounds GEPs. /// - /// 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(this)->stripInBoundsOffsets(); } - /// isDereferenceablePointer - Test if this value is always a pointer to - /// allocated and suitably aligned memory for a simple load or store. + /// \brief Check if this is always a dereferenceable pointer. + /// + /// 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, - /// 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. + /// \brief Translate PHI node to its predecessor from the given basic block. + /// + /// 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 *DoPHITranslation(const BasicBlock *CurBB, const BasicBlock *PredBB); const Value *DoPHITranslation(const BasicBlock *CurBB, @@ -443,11 +453,14 @@ public: return const_cast(this)->DoPHITranslation(CurBB, PredBB); } - /// MaximumAlignment - This is the greatest alignment value supported by - /// load, store, and alloca instructions, and global values. + /// \brief The maximum alignment for instructions. + /// + /// 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 diff --git a/include/llvm/IR/ValueHandle.h b/include/llvm/IR/ValueHandle.h index 1371da5a6c6..460210ebb18 100644 --- a/include/llvm/IR/ValueHandle.h +++ b/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 - /// Node. + /// \brief Add this ValueHandle to the use list after 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 -/// 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 -/// the key of a map (since the map would have to rearrange itself when the -/// pointer changes). +/// \brief Value handle that is nullable, but tries to track the Value. +/// +/// This is a value handle that tries hard to point to a Value, even 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 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 { } }; -/// AssertingVH - This is a Value Handle that points to a value and asserts out -/// 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 -/// non-obvious. One particularly useful place to use this is as the Key of a -/// map. Dangling pointer bugs often lead to really subtle bugs that only occur -/// if another 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. +/// \brief Value handle that asserts if the Value is deleted. +/// +/// This is a Value Handle that points to a value and asserts out 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 non-obvious. +/// One particularly useful place to use this is as the Key of a map. Dangling +/// pointer bugs often lead to really subtle bugs that only occur if another +/// 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 > { }; -/// TrackingVH - This is a value handle that tracks a Value (or Value subclass), -/// even across RAUW operations. +/// \brief Value handle that tracks a Value across RAUW. /// /// 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 -/// 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 -/// takes it out of 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. +/// \brief Value handle with callbacks on RAUW and destruction. +/// +/// This is a value handle that allows subclasses to define 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 takes it out of +/// 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 - /// 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 - /// call setValPtr(NULL). AssertingVH would use this method to cause an - /// assertion failure. + /// \brief Callback for Value destruction. + /// + /// Called when this->getValPtr() is destroyed, inside ~Value(), so you + /// may 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 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 diff --git a/lib/IR/Metadata.cpp b/lib/IR/Metadata.cpp index a017bd3c0c0..cc118496033 100644 --- a/lib/IR/Metadata.cpp +++ b/lib/IR/Metadata.cpp @@ -74,8 +74,7 @@ public: this->setAsFirstOperand(IsFirst); } - /// setAsFirstOperand - Accessor method to mark the operand as the first in - /// the list. + /// \brief Accessor method to mark the operand as the first in 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 -/// the end of the MDNode. +/// \brief Get the MDNodeOperand's coallocated on 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 -/// function-local MDNode. +/// \brief Check if the Value would require a function-local MDNode. static bool isFunctionLocalValue(Value *V) { return isa(V) || isa(V) || isa(V) || (isa(V) && cast(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(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(&*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(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); } diff --git a/lib/IR/User.cpp b/lib/IR/User.cpp index 940682826ac..ee83eacf2b2 100644 --- a/lib/IR/User.cpp +++ b/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? diff --git a/lib/IR/Value.cpp b/lib/IR/Value.cpp index 328154179a3..b5af72b858e 100644 --- a/lib/IR/Value.cpp +++ b/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(this); } -/// isDereferenceablePointer - Test if this value is always a pointer to -/// allocated and suitably aligned memory for a simple load or store. +/// \brief Check if Value is always a dereferenceable pointer. +/// +/// 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 &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(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!");