[nfc] ApplySite argument APIs: cleanup and add comments.

Use consistent terminology, clarify comments, and group APIs.
This matches the documentation in SILDevelopment.md.

Author: atrick

include/swift/SIL/SILInstruction.h

@@ -1936,6 +1936,7 @@ class ApplyInstBase<Impl, Base, true>
     return OperandValueArrayRef(opsWithoutSelf);
   }
 
+  /// Return the SILArgumentConvention for the given applied argument index.
   SILArgumentConvention getArgumentConvention(unsigned index) const {
     return getSubstCalleeConv().getSILArgumentConvention(index);
   }
@@ -7620,47 +7621,59 @@ class ApplySite {
     FOREACH_IMPL_RETURN(getSubstitutionMap());
   }
 
-  /// The arguments passed to this instruction.
+  /// Return the associated specialization information.
+  const GenericSpecializationInformation *getSpecializationInfo() const {
+    FOREACH_IMPL_RETURN(getSpecializationInfo());
+  }
+
+  /// Return an operand list corresponding to the applied arguments.
   MutableArrayRef<Operand> getArgumentOperands() const {
     FOREACH_IMPL_RETURN(getArgumentOperands());
   }
 
-  /// The arguments passed to this instruction.
+  /// Return a list of applied argument values.
   OperandValueArrayRef getArguments() const {
     FOREACH_IMPL_RETURN(getArguments());
   }
 
-  /// The number of call arguments.
+  /// Return the number of applied arguments.
   unsigned getNumArguments() const {
     FOREACH_IMPL_RETURN(getNumArguments());
   }
 
-  unsigned getOperandIndexOfFirstArgument() {
-    FOREACH_IMPL_RETURN(getArgumentOperandNumber());
+  /// Return the apply operand for the given applied argument index.
+  Operand &getArgumentRef(unsigned i) const { return getArgumentOperands()[i]; }
+
+  /// Return the ith applied argument.
+  SILValue getArgument(unsigned i) const { return getArguments()[i]; }
+
+  /// Set the ith applied argument.
+  void setArgument(unsigned i, SILValue V) const {
+    getArgumentOperands()[i].set(V);
   }
 
-  /// Return the associated specialization information.
-  const GenericSpecializationInformation *getSpecializationInfo() const {
-    FOREACH_IMPL_RETURN(getSpecializationInfo());
+  /// Return the operand index of the first applied argument.
+  unsigned getOperandIndexOfFirstArgument() const {
+    FOREACH_IMPL_RETURN(getArgumentOperandNumber());
   }
 #undef FOREACH_IMPL_RETURN
 
-  /// The arguments passed to this instruction, without self.
-  OperandValueArrayRef getArgumentsWithoutSelf() const {
-    switch (Inst->getKind()) {
-    case SILInstructionKind::ApplyInst:
-      return cast<ApplyInst>(Inst)->getArgumentsWithoutSelf();
-    case SILInstructionKind::BeginApplyInst:
-      return cast<BeginApplyInst>(Inst)->getArgumentsWithoutSelf();
-    case SILInstructionKind::TryApplyInst:
-      return cast<TryApplyInst>(Inst)->getArgumentsWithoutSelf();
-    default:
-      llvm_unreachable("not implemented for this instruction!");
-    }
+  /// Returns true if \p oper is an argument operand and not the callee
+  /// operand.
+  bool isArgumentOperand(const Operand &oper) const {
+    return oper.getOperandNumber() >= getOperandIndexOfFirstArgument();
+  }
+
+  /// Return the applied argument index for the given operand.
+  unsigned getArgumentIndex(const Operand &oper) const {
+    assert(oper.getUser() == Inst);
+    assert(isArgumentOperand(oper));
+
+    return oper.getOperandNumber() - getOperandIndexOfFirstArgument();
   }
 
-  // Get the callee argument index corresponding to the caller's first applied
-  // argument. Returns 0 for full applies. May return > 0 for partial applies.
+  /// Return the callee's function argument index corresponding to the first
+  /// applied argument: 0 for full applies; >= 0 for partial applies.
   unsigned getCalleeArgIndexOfFirstAppliedArg() const {
     switch (Inst->getKind()) {
     case SILInstructionKind::ApplyInst:
@@ -7683,35 +7696,30 @@ class ApplySite {
     }
   }
 
-  /// Returns true if \p oper is an argument operand and not the callee
-  /// operand.
-  bool isArgumentOperand(const Operand &oper) {
-    return oper.getOperandNumber() >= getOperandIndexOfFirstArgument();
+  /// Return the callee's function argument index corresponding to the given
+  /// apply operand. Each function argument index identifies a
+  /// SILFunctionArgument in the callee and can be used as a
+  /// SILFunctionConvention argument index.
+  ///
+  /// Note: Passing an applied argument index into SILFunctionConvention, as
+  /// opposed to a function argument index, is incorrect.
+  unsigned getCalleeArgIndex(const Operand &oper) const {
+    return getCalleeArgIndexOfFirstAppliedArg() + getArgumentIndex(oper);
   }
 
-  // Translate the index of the argument to the full apply or partial_apply into
-  // to the corresponding index into the arguments of the called function.
-  unsigned getCalleeArgIndex(const Operand &oper) {
-    assert(oper.getUser() == Inst);
-    assert(isArgumentOperand(oper));
-
-    unsigned appliedArgIdx =
-        oper.getOperandNumber() - getOperandIndexOfFirstArgument();
-
-    return getCalleeArgIndexOfFirstAppliedArg() + appliedArgIdx;
+  /// Return the SILArgumentConvention for the given applied argument operand.
+  SILArgumentConvention getArgumentConvention(Operand &oper) const {
+    unsigned calleeArgIdx =
+      getCalleeArgIndexOfFirstAppliedArg() + getArgumentIndex(oper);
+    return getSubstCalleeConv().getSILArgumentConvention(calleeArgIdx);
   }
 
-  Operand &getArgumentRef(unsigned i) const { return getArgumentOperands()[i]; }
-
-  /// Return the ith argument passed to this instruction.
-  SILValue getArgument(unsigned i) const { return getArguments()[i]; }
-
-  /// Set the ith argument of this instruction.
-  void setArgument(unsigned i, SILValue V) const {
-    getArgumentOperands()[i].set(V);
+  // FIXME: This is incorrect. It will be removed in the next commit.
+  SILArgumentConvention getArgumentConvention(unsigned index) const {
+    return getSubstCalleeConv().getSILArgumentConvention(index);
   }
 
-  /// Return the self argument passed to this instruction.
+  /// Return true if 'self' is an applied argument.
   bool hasSelfArgument() const {
     switch (Inst->getKind()) {
     case SILInstructionKind::ApplyInst:
@@ -7725,7 +7733,7 @@ class ApplySite {
     }
   }
 
-  /// Return the self argument passed to this instruction.
+  /// Return the applied 'self' argument value.
   SILValue getSelfArgument() const {
     switch (Inst->getKind()) {
     case SILInstructionKind::ApplyInst:
@@ -7739,7 +7747,7 @@ class ApplySite {
     }
   }
 
-  /// Return the self operand passed to this instruction.
+  /// Return the 'self' apply operand.
   Operand &getSelfArgumentOperand() {
     switch (Inst->getKind()) {
     case SILInstructionKind::ApplyInst:
@@ -7753,8 +7761,18 @@ class ApplySite {
     }
   }
 
-  SILArgumentConvention getArgumentConvention(unsigned index) const {
-    return getSubstCalleeConv().getSILArgumentConvention(index);
+  /// Return a list of applied arguments without self.
+  OperandValueArrayRef getArgumentsWithoutSelf() const {
+    switch (Inst->getKind()) {
+    case SILInstructionKind::ApplyInst:
+      return cast<ApplyInst>(Inst)->getArgumentsWithoutSelf();
+    case SILInstructionKind::BeginApplyInst:
+      return cast<BeginApplyInst>(Inst)->getArgumentsWithoutSelf();
+    case SILInstructionKind::TryApplyInst:
+      return cast<TryApplyInst>(Inst)->getArgumentsWithoutSelf();
+    default:
+      llvm_unreachable("not implemented for this instruction!");
+    }
   }
 
   static ApplySite getFromOpaqueValue(void *p) {