fix documentation comments; NFC

llvm-svn: 294964

include/llvm/IR/CallSite.h

@@ -65,11 +65,9 @@ protected:
   explicit CallSiteBase(ValTy *II) { *this = get(II); }
 
 private:
-  /// CallSiteBase::get - This static method is sort of like a constructor.  It
+  /// This static method is like a constructor. It will create an appropriate
-  /// will create an appropriate call site for a Call or Invoke instruction, but
+  /// call site for a Call or Invoke instruction, but it can also create a null
-  /// it can also create a null initialized CallSiteBase object for something
+  /// initialized CallSiteBase object for something which is NOT a call site.
-  /// which is NOT a call site.
-  ///
   static CallSiteBase get(ValTy *V) {
     if (InstrTy *II = dyn_cast<InstrTy>(V)) {
       if (II->getOpcode() == Instruction::Call)
@@ -81,37 +79,33 @@ private:
   }
 
 public:
-  /// isCall - true if a CallInst is enclosed.
+  /// Return true if a CallInst is enclosed. Note that !isCall() does not mean
-  /// Note that !isCall() does not mean it is an InvokeInst enclosed,
+  /// an InvokeInst is enclosed. It may also signify a NULL instruction pointer.
-  /// it also could signify a NULL Instruction pointer.
   bool isCall() const { return I.getInt(); }
 
-  /// isInvoke - true if a InvokeInst is enclosed.
+  /// Return true if a InvokeInst is enclosed.
-  ///
   bool isInvoke() const { return getInstruction() && !I.getInt(); }
 
   InstrTy *getInstruction() const { return I.getPointer(); }
   InstrTy *operator->() const { return I.getPointer(); }
   explicit operator bool() const { return I.getPointer(); }
 
-  /// Get the basic block containing the call site
+  /// Get the basic block containing the call site.
   BBTy* getParent() const { return getInstruction()->getParent(); }
 
-  /// getCalledValue - Return the pointer to function that is being called.
+  /// Return the pointer to function that is being called.
-  ///
   ValTy *getCalledValue() const {
     assert(getInstruction() && "Not a call or invoke instruction!");
     return *getCallee();
   }
 
-  /// getCalledFunction - Return the function being called if this is a direct
+  /// Return the function being called if this is a direct call, otherwise
-  /// call, otherwise return null (if it's an indirect call).
+  /// return null (if it's an indirect call).
-  ///
   FunTy *getCalledFunction() const {
     return dyn_cast<FunTy>(getCalledValue());
   }
 
-  /// Returns true if the callsite is an indirect call
+  /// Return true if the callsite is an indirect call.
   bool isIndirectCall() const {
     Value *V = getCalledValue();
     if (!V)
@@ -125,8 +119,7 @@ public:
     return true;
   }
 
-  /// setCalledFunction - Set the callee to the specified value.
+  /// Set the callee to the specified value.
-  ///
   void setCalledFunction(Value *V) {
     assert(getInstruction() && "Not a call or invoke instruction!");
     *getCallee() = V;
@@ -143,8 +136,7 @@ public:
     return static_cast<Intrinsic::ID>(0);
   }
 
-  /// isCallee - Determine whether the passed iterator points to the
+  /// Determine whether the passed iterator points to the callee operand's Use.
-  /// callee operand's Use.
   bool isCallee(Value::const_user_iterator UI) const {
     return isCallee(&UI.getUse());
   }
@@ -152,24 +144,23 @@ public:
   /// Determine whether this Use is the callee operand's Use.
   bool isCallee(const Use *U) const { return getCallee() == U; }
 
-  /// \brief Determine whether the passed iterator points to an argument
+  /// Determine whether the passed iterator points to an argument operand.
-  /// operand.
   bool isArgOperand(Value::const_user_iterator UI) const {
     return isArgOperand(&UI.getUse());
   }
 
-  /// \brief Determine whether the passed use points to an argument operand.
+  /// Determine whether the passed use points to an argument operand.
   bool isArgOperand(const Use *U) const {
     assert(getInstruction() == U->getUser());
     return arg_begin() <= U && U < arg_end();
   }
 
-  /// \brief Determine whether the passed iterator points to a bundle operand.
+  /// Determine whether the passed iterator points to a bundle operand.
   bool isBundleOperand(Value::const_user_iterator UI) const {
     return isBundleOperand(&UI.getUse());
   }
 
-  /// \brief Determine whether the passed use points to a bundle operand.
+  /// Determine whether the passed use points to a bundle operand.
   bool isBundleOperand(const Use *U) const {
     assert(getInstruction() == U->getUser());
     if (!hasOperandBundles())
@@ -179,12 +170,12 @@ public:
            OperandNo < getBundleOperandsEndIndex();
   }
 
-  /// \brief Determine whether the passed iterator points to a data operand.
+  /// Determine whether the passed iterator points to a data operand.
   bool isDataOperand(Value::const_user_iterator UI) const {
     return isDataOperand(&UI.getUse());
   }
 
-  /// \brief Determine whether the passed use points to a data operand.
+  /// Determine whether the passed use points to a data operand.
   bool isDataOperand(const Use *U) const {
     return data_operands_begin() <= U && U < data_operands_end();
   }
@@ -214,8 +205,8 @@ public:
     return U - arg_begin();
   }
 
-  /// arg_iterator - The type of iterator to use when looping over actual
+  /// The type of iterator to use when looping over actual arguments at this
-  /// arguments at this call site.
+  /// call site.
   typedef IterTy arg_iterator;
 
   iterator_range<IterTy> args() const {
@@ -224,8 +215,7 @@ public:
   bool arg_empty() const { return arg_end() == arg_begin(); }
   unsigned arg_size() const { return unsigned(arg_end() - arg_begin()); }
 
-  /// Given a value use iterator, returns the data operand that corresponds to
+  /// Given a value use iterator, return the data operand corresponding to it.
-  /// it.
   /// Iterator must actually correspond to a data operand.
   unsigned getDataOperandNo(Value::const_user_iterator UI) const {
     return getDataOperandNo(&UI.getUse());
@@ -267,21 +257,19 @@ public:
     return std::distance(data_operands_begin(), data_operands_end());
   }
 
-  /// getType - Return the type of the instruction that generated this call site
+  /// Return the type of the instruction that generated this call site.
-  ///
   Type *getType() const { return (*this)->getType(); }
 
-  /// getCaller - Return the caller function for this call site
+  /// Return the caller function for this call site.
-  ///
   FunTy *getCaller() const { return (*this)->getParent()->getParent(); }
 
-  /// \brief Tests if this call site must be tail call optimized.  Only a
+  /// Tests if this call site must be tail call optimized. Only a CallInst can
-  /// CallInst can be tail call optimized.
+  /// be tail call optimized.
   bool isMustTailCall() const {
     return isCall() && cast<CallInst>(getInstruction())->isMustTailCall();
   }
 
-  /// \brief Tests if this call site is marked as a tail call.
+  /// Tests if this call site is marked as a tail call.
   bool isTailCall() const {
     return isCall() && cast<CallInst>(getInstruction())->isTailCall();
   }
@@ -317,11 +305,11 @@ public:
     return false;
   }
 
-  /// getCallingConv/setCallingConv - get or set the calling convention of the
+  /// Get the calling convention of the call.
-  /// call.
   CallingConv::ID getCallingConv() const {
     CALLSITE_DELEGATE_GETTER(getCallingConv());
   }
+  /// Set the calling convention of the call.
   void setCallingConv(CallingConv::ID CC) {
     CALLSITE_DELEGATE_SETTER(setCallingConv(CC));
   }
@@ -334,11 +322,11 @@ public:
     CALLSITE_DELEGATE_SETTER(mutateFunctionType(Ty));
   }
 
-  /// getAttributes/setAttributes - get or set the parameter attributes of
+  /// Get the parameter attributes of the call.
-  /// the call.
   AttributeSet getAttributes() const {
     CALLSITE_DELEGATE_GETTER(getAttributes());
   }
+  /// Set the parameter attributes of the call.
   void setAttributes(AttributeSet PAL) {
     CALLSITE_DELEGATE_SETTER(setAttributes(PAL));
   }
@@ -359,17 +347,17 @@ public:
     CALLSITE_DELEGATE_SETTER(removeAttribute(i, Kind));
   }
 
-  /// \brief Return true if this function has the given attribute.
+  /// Return true if this function has the given attribute.
   bool hasFnAttr(Attribute::AttrKind Kind) const {
     CALLSITE_DELEGATE_GETTER(hasFnAttr(Kind));
   }
 
-  /// \brief Return true if this function has the given attribute.
+  /// Return true if this function has the given attribute.
   bool hasFnAttr(StringRef Kind) const {
     CALLSITE_DELEGATE_GETTER(hasFnAttr(Kind));
   }
 
-  /// \brief Return true if the call or the callee has the given attribute.
+  /// Return true if the call or the callee has the given attribute.
   bool paramHasAttr(unsigned i, Attribute::AttrKind Kind) const {
     CALLSITE_DELEGATE_GETTER(paramHasAttr(i, Kind));
   }
@@ -382,8 +370,8 @@ public:
     CALLSITE_DELEGATE_GETTER(getAttribute(i, Kind));
   }
 
-  /// \brief Return true if the data operand at index \p i directly or
+  /// Return true if the data operand at index \p i directly or indirectly has
-  /// indirectly has the attribute \p A.
+  /// the attribute \p A.
   ///
   /// Normal call or invoke arguments have per operand attributes, as specified
   /// in the attribute set attached to this instruction, while operand bundle
@@ -393,37 +381,36 @@ public:
     CALLSITE_DELEGATE_GETTER(dataOperandHasImpliedAttr(i, Kind));
   }
 
-  /// @brief Extract the alignment for a call or parameter (0=unknown).
+  /// Extract the alignment for a call or parameter (0=unknown).
   uint16_t getParamAlignment(uint16_t i) const {
     CALLSITE_DELEGATE_GETTER(getParamAlignment(i));
   }
 
-  /// @brief Extract the number of dereferenceable bytes for a call or
+  /// Extract the number of dereferenceable bytes for a call or parameter
-  /// parameter (0=unknown).
+  /// (0=unknown).
   uint64_t getDereferenceableBytes(uint16_t i) const {
     CALLSITE_DELEGATE_GETTER(getDereferenceableBytes(i));
   }
 
-  /// @brief Extract the number of dereferenceable_or_null bytes for a call or
+  /// Extract the number of dereferenceable_or_null bytes for a call or
   /// parameter (0=unknown).
   uint64_t getDereferenceableOrNullBytes(uint16_t i) const {
     CALLSITE_DELEGATE_GETTER(getDereferenceableOrNullBytes(i));
   }
 
-  /// @brief Determine if the parameter or return value is marked with NoAlias
+  /// Determine if the parameter or return value is marked with NoAlias
   /// attribute.
   /// @param n The parameter to check. 1 is the first parameter, 0 is the return
   bool doesNotAlias(unsigned n) const {
     CALLSITE_DELEGATE_GETTER(doesNotAlias(n));
   }
 
-  /// \brief Return true if the call should not be treated as a call to a
+  /// Return true if the call should not be treated as a call to a builtin.
-  /// builtin.
   bool isNoBuiltin() const {
     CALLSITE_DELEGATE_GETTER(isNoBuiltin());
   }
 
-  /// @brief Return true if the call should not be inlined.
+  /// Return true if the call should not be inlined.
   bool isNoInline() const {
     CALLSITE_DELEGATE_GETTER(isNoInline());
   }
@@ -431,7 +418,7 @@ public:
     CALLSITE_DELEGATE_SETTER(setIsNoInline(Value));
   }
 
-  /// @brief Determine if the call does not access memory.
+  /// Determine if the call does not access memory.
   bool doesNotAccessMemory() const {
     CALLSITE_DELEGATE_GETTER(doesNotAccessMemory());
   }
@@ -439,7 +426,7 @@ public:
     CALLSITE_DELEGATE_SETTER(setDoesNotAccessMemory());
   }
 
-  /// @brief Determine if the call does not access or only reads memory.
+  /// Determine if the call does not access or only reads memory.
   bool onlyReadsMemory() const {
     CALLSITE_DELEGATE_GETTER(onlyReadsMemory());
   }
@@ -447,7 +434,7 @@ public:
     CALLSITE_DELEGATE_SETTER(setOnlyReadsMemory());
   }
 
-  /// @brief Determine if the call does not access or only writes memory.
+  /// Determine if the call does not access or only writes memory.
   bool doesNotReadMemory() const {
     CALLSITE_DELEGATE_GETTER(doesNotReadMemory());
   }
@@ -455,7 +442,7 @@ public:
     CALLSITE_DELEGATE_SETTER(setDoesNotReadMemory());
   }
 
-  /// @brief Determine if the call can access memmory only using pointers based
+  /// Determine if the call can access memmory only using pointers based
   /// on its arguments.
   bool onlyAccessesArgMemory() const {
     CALLSITE_DELEGATE_GETTER(onlyAccessesArgMemory());
@@ -464,7 +451,7 @@ public:
     CALLSITE_DELEGATE_SETTER(setOnlyAccessesArgMemory());
   }
 
-  /// @brief Determine if the call cannot return.
+  /// Determine if the call cannot return.
   bool doesNotReturn() const {
     CALLSITE_DELEGATE_GETTER(doesNotReturn());
   }
@@ -472,7 +459,7 @@ public:
     CALLSITE_DELEGATE_SETTER(setDoesNotReturn());
   }
 
-  /// @brief Determine if the call cannot unwind.
+  /// Determine if the call cannot unwind.
   bool doesNotThrow() const {
     CALLSITE_DELEGATE_GETTER(doesNotThrow());
   }
@@ -480,7 +467,7 @@ public:
     CALLSITE_DELEGATE_SETTER(setDoesNotThrow());
   }
 
-  /// @brief Determine if the call can be duplicated.
+  /// Determine if the call can be duplicated.
   bool cannotDuplicate() const {
     CALLSITE_DELEGATE_GETTER(cannotDuplicate());
   }
@@ -488,7 +475,7 @@ public:
     CALLSITE_DELEGATE_GETTER(setCannotDuplicate());
   }
 
-  /// @brief Determine if the call is convergent.
+  /// Determine if the call is convergent.
   bool isConvergent() const {
     CALLSITE_DELEGATE_GETTER(isConvergent());
   }
@@ -560,29 +547,29 @@ public:
       cast<InvokeInst>(II)->getOperandBundlesAsDefs(Defs);
   }
 
-  /// @brief Determine whether this data operand is not captured.
+  /// Determine whether this data operand is not captured.
   bool doesNotCapture(unsigned OpNo) const {
     return dataOperandHasImpliedAttr(OpNo + 1, Attribute::NoCapture);
   }
 
-  /// @brief Determine whether this argument is passed by value.
+  /// Determine whether this argument is passed by value.
   bool isByValArgument(unsigned ArgNo) const {
     return paramHasAttr(ArgNo + 1, Attribute::ByVal);
   }
 
-  /// @brief Determine whether this argument is passed in an alloca.
+  /// Determine whether this argument is passed in an alloca.
   bool isInAllocaArgument(unsigned ArgNo) const {
     return paramHasAttr(ArgNo + 1, Attribute::InAlloca);
   }
 
-  /// @brief Determine whether this argument is passed by value or in an alloca.
+  /// Determine whether this argument is passed by value or in an alloca.
   bool isByValOrInAllocaArgument(unsigned ArgNo) const {
     return paramHasAttr(ArgNo + 1, Attribute::ByVal) ||
            paramHasAttr(ArgNo + 1, Attribute::InAlloca);
   }
 
-  /// @brief Determine if there are is an inalloca argument.  Only the last
+  /// Determine if there are is an inalloca argument. Only the last argument can
-  /// argument can have the inalloca attribute.
+  /// have the inalloca attribute.
   bool hasInAllocaArgument() const {
     return paramHasAttr(arg_size(), Attribute::InAlloca);
   }
@@ -596,7 +583,7 @@ public:
            dataOperandHasImpliedAttr(OpNo + 1, Attribute::ReadNone);
   }
 
-  /// @brief Return true if the return value is known to be not null.
+  /// Return true if the return value is known to be not null.
   /// This may be because it has the nonnull attribute, or because at least
   /// one byte is dereferenceable and the pointer is in addrspace(0).
   bool isReturnNonNull() const {
@@ -609,8 +596,8 @@ public:
     return false;
   }
 
-  /// hasArgument - Returns true if this CallSite passes the given Value* as an
+  /// Returns true if this CallSite passes the given Value* as an argument to
-  /// argument to the called function.
+  /// the called function.
   bool hasArgument(const Value *Arg) const {
     for (arg_iterator AI = this->arg_begin(), E = this->arg_end(); AI != E;
          ++AI)
@@ -675,7 +662,7 @@ template <> struct DenseMapInfo<CallSite> {
   }
 };
 
-/// ImmutableCallSite - establish a view to a call site for examination
+/// Establish a view to a call site for examination.
 class ImmutableCallSite : public CallSiteBase<> {
 public:
   ImmutableCallSite() = default;