OwnershipOptUtils API comments. Document assumed preconditions.

Author: atrick

include/swift/SILOptimizer/Utils/OwnershipOptUtils.h

@@ -128,6 +128,11 @@ class OwnershipRAUWHelper {
   ///
   /// \p oldValue may be either a SingleValueInstruction or a terminator result.
   ///
+  /// Precondition: If \p oldValue is a BorrowedValue that introduces a local
+  /// borrow scope, then \p newValue must either be defined in the same block as
+  /// \p oldValue, or it must dominate \p oldValue (rather than merely
+  /// dominating its uses).
+  ///
   /// DISCUSSION: We do not check that the types line up here so that we can
   /// allow for our users to transform our new value in ways that preserve
   /// ownership at \p oldValue before we perform the actual RAUW. If \p newValue
@@ -168,6 +173,9 @@ class OwnershipRAUWHelper {
 /// a single use of a value with another value with a different ownership. We
 /// allow for the values to have different types.
 ///
+/// Precondition: if \p use ends a borrow scope, then \p newValue dominates the
+/// BorrowedValue that begins the scope.
+///
 /// NOTE: When not in OSSA, this just performs a normal set use, so this code is
 /// safe to use with all code.
 class OwnershipReplaceSingleUseHelper {