AST: Integrate variance positions into the type transform

While we're here, also tidy up the documentation for the type transform APIs

Author: AnthonyLatsis

include/swift/AST/Type.h

@@ -269,47 +269,47 @@ class Type {
   /// its children.
   bool findIf(llvm::function_ref<bool(Type)> pred) const;
 
-  /// Transform the given type by applying the user-provided function to
-  /// each type.
+  /// Transform the given type by recursively applying the user-provided
+  /// function to each node.
   ///
-  /// This routine applies the given function to transform one type into
-  /// another. If the function leaves the type unchanged, recurse into the
-  /// child type nodes and transform those. If any child type node changes,
-  /// the parent type node will be rebuilt.
-  ///
-  /// If at any time the function returns a null type, the null will be
-  /// propagated out.
-  ///
-  /// \param fn A function object with the signature \c Type(Type), which
-  /// accepts a type and returns either a transformed type or a null type.
+  /// \param fn A function object with the signature \c Type(Type) , which
+  /// accepts a type and returns either a transformed type or a null type
+  /// (which will propagate out the null type).
   ///
   /// \returns the result of transforming the type.
   Type transform(llvm::function_ref<Type(Type)> fn) const;
 
-  /// Transform the given type by applying the user-provided function to
-  /// each type.
-  ///
-  /// This routine applies the given function to transform one type into
-  /// another. If the function leaves the type unchanged, recurse into the
-  /// child type nodes and transform those. If any child type node changes,
-  /// the parent type node will be rebuilt.
-  ///
-  /// If at any time the function returns a null type, the null will be
-  /// propagated out.
+  /// Transform the given type by recursively applying the user-provided
+  /// function to each node.
   ///
   /// If the function returns \c None, the transform operation will
   ///
-  /// \param fn A function object with the signature
-  /// \c Optional<Type>(TypeBase *), which accepts a type pointer and returns a
-  /// transformed type, a null type (which will propagate the null type to the
-  /// outermost \c transform() call), or None (to indicate that the transform
-  /// operation should recursively transform the subtypes). The function object
-  /// should use \c dyn_cast rather \c getAs, because the transform itself
-  /// handles desugaring.
+  /// \param fn A function object which accepts a type pointer and returns a
+  /// transformed type, a null type (which will propagate out the null type),
+  /// or None (to indicate that the transform operation should recursively
+  /// transform the children). The function object should use \c dyn_cast rather
+  /// than \c getAs when the transform is intended to preserve sugar
   ///
   /// \returns the result of transforming the type.
   Type transformRec(llvm::function_ref<Optional<Type>(TypeBase *)> fn) const;
 
+  /// Transform the given type by recursively applying the user-provided
+  /// function to each node.
+  ///
+  /// \param pos The variance position of the receiver.
+  ///
+  /// \param fn A function object which accepts a type pointer along with its
+  /// variance position and returns either a transformed type, a null type
+  /// (which will propagate out the null type), or \c None (to indicate that the
+  /// transform operation should recursively transform the children).
+  /// The function object should use \c dyn_cast rather than \c getAs when the
+  /// transform is intended to preserve sugar.
+  ///
+  /// \returns the result of transforming the type.
+  Type transformWithPosition(
+      TypePosition pos,
+      llvm::function_ref<Optional<Type>(TypeBase *, TypePosition)> fn) const;
+
   /// Look through the given type and its children and apply fn to them.
   void visit(llvm::function_ref<void (Type)> fn) const {
     findIf([&fn](Type t) -> bool {