From 8e3352072c473d731199e4c43013dd9d2aa687c9 Mon Sep 17 00:00:00 2001 From: Sanjay Patel Date: Sat, 12 Mar 2016 20:44:30 +0000 Subject: [PATCH] fix documentation comments; NFC llvm-svn: 263345 --- include/llvm/IR/Instruction.h | 138 +++++++++++++++------------------- 1 file changed, 62 insertions(+), 76 deletions(-) diff --git a/include/llvm/IR/Instruction.h b/include/llvm/IR/Instruction.h index 03c45497fa9..12cbcce4c09 100644 --- a/include/llvm/IR/Instruction.h +++ b/include/llvm/IR/Instruction.h @@ -42,23 +42,23 @@ class Instruction : public User, DebugLoc DbgLoc; // 'dbg' Metadata cache. enum { - /// HasMetadataBit - This is a bit stored in the SubClassData field which - /// indicates whether this instruction has metadata attached to it or not. + /// This is a bit stored in the SubClassData field which indicates whether + /// this instruction has metadata attached to it or not. HasMetadataBit = 1 << 15 }; public: // Out of line virtual method, so the vtable, etc has a home. ~Instruction() override; - /// user_back - Specialize the methods defined in Value, as we know that an - /// instruction can only be used by other instructions. + /// Specialize the methods defined in Value, as we know that an instruction + /// can only be used by other instructions. Instruction *user_back() { return cast(*user_begin());} const Instruction *user_back() const { return cast(*user_begin());} inline const BasicBlock *getParent() const { return Parent; } inline BasicBlock *getParent() { return Parent; } - /// \brief Return the module owning the function this instruction belongs to + /// Return the module owning the function this instruction belongs to /// or nullptr it the function does not have a module. /// /// Note: this is undefined behavior if the instruction does not have a @@ -66,20 +66,18 @@ public: const Module *getModule() const; Module *getModule(); - /// \brief Return the function this instruction belongs to. + /// Return the function this instruction belongs to. /// /// Note: it is undefined behavior to call this on an instruction not /// currently inserted into a function. const Function *getFunction() const; Function *getFunction(); - /// removeFromParent - This method unlinks 'this' from the containing basic - /// block, but does not delete it. - /// + /// This method unlinks 'this' from the containing basic block, but does not + /// delete it. void removeFromParent(); - /// eraseFromParent - This method unlinks 'this' from the containing basic - /// block and deletes it. + /// This method unlinks 'this' from the containing basic block and deletes it. /// /// \returns an iterator pointing to the element after the erased one SymbolTableList::iterator eraseFromParent(); @@ -92,16 +90,15 @@ public: /// specified instruction. void insertAfter(Instruction *InsertPos); - /// moveBefore - Unlink this instruction from its current basic block and - /// insert it into the basic block that MovePos lives in, right before - /// MovePos. + /// Unlink this instruction from its current basic block and insert it into + /// the basic block that MovePos lives in, right before MovePos. void moveBefore(Instruction *MovePos); //===--------------------------------------------------------------------===// // Subclass classification. //===--------------------------------------------------------------------===// - /// getOpcode() returns a member of one of the enums like Instruction::Add. + /// Returns a member of one of the enums like Instruction::Add. unsigned getOpcode() const { return getValueID() - InstructionVal; } const char *getOpcodeName() const { return getOpcodeName(getOpcode()); } @@ -121,28 +118,27 @@ public: return Opcode >= BinaryOpsBegin && Opcode < BinaryOpsEnd; } - /// @brief Determine if the Opcode is one of the shift instructions. + /// Determine if the Opcode is one of the shift instructions. static inline bool isShift(unsigned Opcode) { return Opcode >= Shl && Opcode <= AShr; } - /// isLogicalShift - Return true if this is a logical shift left or a logical - /// shift right. + /// Return true if this is a logical shift left or a logical shift right. inline bool isLogicalShift() const { return getOpcode() == Shl || getOpcode() == LShr; } - /// isArithmeticShift - Return true if this is an arithmetic shift right. + /// Return true if this is an arithmetic shift right. inline bool isArithmeticShift() const { return getOpcode() == AShr; } - /// @brief Determine if the OpCode is one of the CastInst instructions. + /// Determine if the OpCode is one of the CastInst instructions. static inline bool isCast(unsigned OpCode) { return OpCode >= CastOpsBegin && OpCode < CastOpsEnd; } - /// @brief Determine if the OpCode is one of the FuncletPadInst instructions. + /// Determine if the OpCode is one of the FuncletPadInst instructions. static inline bool isFuncletPad(unsigned OpCode) { return OpCode >= FuncletPadOpsBegin && OpCode < FuncletPadOpsEnd; } @@ -151,55 +147,53 @@ public: // Metadata manipulation. //===--------------------------------------------------------------------===// - /// hasMetadata() - Return true if this instruction has any metadata attached - /// to it. + /// Return true if this instruction has any metadata attached to it. bool hasMetadata() const { return DbgLoc || hasMetadataHashEntry(); } - /// hasMetadataOtherThanDebugLoc - Return true if this instruction has - /// metadata attached to it other than a debug location. + /// Return true if this instruction has metadata attached to it other than a + /// debug location. bool hasMetadataOtherThanDebugLoc() const { return hasMetadataHashEntry(); } - /// getMetadata - Get the metadata of given kind attached to this Instruction. + /// Get the metadata of given kind attached to this Instruction. /// If the metadata is not found then return null. MDNode *getMetadata(unsigned KindID) const { if (!hasMetadata()) return nullptr; return getMetadataImpl(KindID); } - /// getMetadata - Get the metadata of given kind attached to this Instruction. + /// Get the metadata of given kind attached to this Instruction. /// If the metadata is not found then return null. MDNode *getMetadata(StringRef Kind) const { if (!hasMetadata()) return nullptr; return getMetadataImpl(Kind); } - /// getAllMetadata - Get all metadata attached to this Instruction. The first - /// element of each pair returned is the KindID, the second element is the - /// metadata value. This list is returned sorted by the KindID. + /// Get all metadata attached to this Instruction. The first element of each + /// pair returned is the KindID, the second element is the metadata value. + /// This list is returned sorted by the KindID. void getAllMetadata(SmallVectorImpl> &MDs) const { if (hasMetadata()) getAllMetadataImpl(MDs); } - /// getAllMetadataOtherThanDebugLoc - This does the same thing as - /// getAllMetadata, except that it filters out the debug location. + /// This does the same thing as getAllMetadata, except that it filters out the + /// debug location. void getAllMetadataOtherThanDebugLoc( SmallVectorImpl> &MDs) const { if (hasMetadataOtherThanDebugLoc()) getAllMetadataOtherThanDebugLocImpl(MDs); } - /// getAAMetadata - Fills the AAMDNodes structure with AA metadata from - /// this instruction. When Merge is true, the existing AA metadata is - /// merged with that from this instruction providing the most-general result. + /// Fills the AAMDNodes structure with AA metadata from this instruction. + /// When Merge is true, the existing AA metadata is merged with that from this + /// instruction providing the most-general result. void getAAMetadata(AAMDNodes &N, bool Merge = false) const; - /// setMetadata - Set the metadata of the specified kind to the specified - /// node. This updates/replaces metadata if already present, or removes it if - /// Node is null. + /// Set the metadata of the specified kind to the specified node. This updates + /// or replaces metadata if already present, or removes it if Node is null. void setMetadata(unsigned KindID, MDNode *Node); void setMetadata(StringRef Kind, MDNode *Node); @@ -220,14 +214,13 @@ public: } /// @} - /// setAAMetadata - Sets the metadata on this instruction from the - /// AAMDNodes structure. + /// Sets the metadata on this instruction from the AAMDNodes structure. void setAAMetadata(const AAMDNodes &N); - /// setDebugLoc - Set the debug location information for this instruction. + /// Set the debug location information for this instruction. void setDebugLoc(DebugLoc Loc) { DbgLoc = std::move(Loc); } - /// getDebugLoc - Return the debug location for this node as a DebugLoc. + /// Return the debug location for this node as a DebugLoc. const DebugLoc &getDebugLoc() const { return DbgLoc; } /// Set or clear the unsafe-algebra flag on this instruction, which must be an @@ -289,8 +282,7 @@ public: void copyFastMathFlags(const Instruction *I); private: - /// hasMetadataHashEntry - Return true if we have an entry in the on-the-side - /// metadata hash. + /// Return true if we have an entry in the on-the-side metadata hash. bool hasMetadataHashEntry() const { return (getSubclassDataFromValue() & HasMetadataBit) != 0; } @@ -302,6 +294,7 @@ private: getAllMetadataImpl(SmallVectorImpl> &) const; void getAllMetadataOtherThanDebugLocImpl( SmallVectorImpl> &) const; + /// Clear all hashtable-based metadata from this instruction. void clearMetadataHashEntries(); public: //===--------------------------------------------------------------------===// @@ -309,7 +302,7 @@ public: //===--------------------------------------------------------------------===// - /// isAssociative - Return true if the instruction is associative: + /// Return true if the instruction is associative: /// /// Associative operators satisfy: x op (y op z) === (x op y) op z /// @@ -318,7 +311,7 @@ public: bool isAssociative() const; static bool isAssociative(unsigned op); - /// isCommutative - Return true if the instruction is commutative: + /// Return true if the instruction is commutative: /// /// Commutative operators satisfy: (x op y) === (y op x) /// @@ -328,7 +321,7 @@ public: bool isCommutative() const { return isCommutative(getOpcode()); } static bool isCommutative(unsigned op); - /// isIdempotent - Return true if the instruction is idempotent: + /// Return true if the instruction is idempotent: /// /// Idempotent operators satisfy: x op x === x /// @@ -337,7 +330,7 @@ public: bool isIdempotent() const { return isIdempotent(getOpcode()); } static bool isIdempotent(unsigned op); - /// isNilpotent - Return true if the instruction is nilpotent: + /// Return true if the instruction is nilpotent: /// /// Nilpotent operators satisfy: x op x === Id, /// @@ -349,37 +342,31 @@ public: bool isNilpotent() const { return isNilpotent(getOpcode()); } static bool isNilpotent(unsigned op); - /// mayWriteToMemory - Return true if this instruction may modify memory. - /// + /// Return true if this instruction may modify memory. bool mayWriteToMemory() const; - /// mayReadFromMemory - Return true if this instruction may read memory. - /// + /// Return true if this instruction may read memory. bool mayReadFromMemory() const; - /// mayReadOrWriteMemory - Return true if this instruction may read or - /// write memory. - /// + /// Return true if this instruction may read or write memory. bool mayReadOrWriteMemory() const { return mayReadFromMemory() || mayWriteToMemory(); } - /// isAtomic - Return true if this instruction has an - /// AtomicOrdering of unordered or higher. - /// + /// Return true if this instruction has an AtomicOrdering of unordered or + /// higher. bool isAtomic() const; - /// mayThrow - Return true if this instruction may throw an exception. - /// + /// Return true if this instruction may throw an exception. bool mayThrow() const; - /// mayReturn - Return true if this is a function that may return. - /// this is true for all normal instructions. The only exception + /// Return true if this is a function that may return. + /// This is true for all normal instructions. The only exception /// is functions that are marked with the 'noreturn' attribute. /// bool mayReturn() const; - /// mayHaveSideEffects - Return true if the instruction may have side effects. + /// Return true if the instruction may have side effects. /// /// Note that this does not consider malloc and alloca to have side /// effects because the newly allocated memory is completely invisible to @@ -389,7 +376,7 @@ public: return mayWriteToMemory() || mayThrow() || !mayReturn(); } - /// \brief Return true if the instruction is a variety of EH-block. + /// Return true if the instruction is a variety of EH-block. bool isEHPad() const { switch (getOpcode()) { case Instruction::CatchSwitch: @@ -402,21 +389,21 @@ public: } } - /// clone() - Create a copy of 'this' instruction that is identical in all - /// ways except the following: + /// Create a copy of 'this' instruction that is identical in all ways except + /// the following: /// * The instruction has no parent /// * The instruction has no name /// Instruction *clone() const; - /// isIdenticalTo - Return true if the specified instruction is exactly - /// identical to the current one. This means that all operands match and any - /// extra information (e.g. load is volatile) agree. + /// Return true if the specified instruction is exactly identical to the + /// current one. This means that all operands match and any extra information + /// (e.g. load is volatile) agree. bool isIdenticalTo(const Instruction *I) const; - /// isIdenticalToWhenDefined - This is like isIdenticalTo, except that it - /// ignores the SubclassOptionalData flags, which specify conditions - /// under which the instruction's result is undefined. + /// This is like isIdenticalTo, except that it ignores the + /// SubclassOptionalData flags, which specify conditions under which the + /// instruction's result is undefined. bool isIdenticalToWhenDefined(const Instruction *I) const; /// When checking for operation equivalence (using isSameOperationAs) it is @@ -439,10 +426,9 @@ public: /// @brief Determine if one instruction is the same operation as another. bool isSameOperationAs(const Instruction *I, unsigned flags = 0) const; - /// isUsedOutsideOfBlock - Return true if there are any uses of this - /// instruction in blocks other than the specified block. Note that PHI nodes - /// are considered to evaluate their operands in the corresponding predecessor - /// block. + /// Return true if there are any uses of this instruction in blocks other than + /// the specified block. Note that PHI nodes are considered to evaluate their + /// operands in the corresponding predecessor block. bool isUsedOutsideOfBlock(const BasicBlock *BB) const;