Merge pull request #5994 from Gankro/doc-ptr

Fixups for UnsafePointer documentation

Author: natecook1000

stdlib/public/core/UnsafePointer.swift.gyb

@@ -432,21 +432,29 @@ public struct ${Self}<Pointee>
   }
 
   /// Returns the next consecutive position.
+  ///
+  /// - Precondition: The result is within the bounds of the same allocation.
   public func successor() -> ${Self} {
     return self + 1
   }
 
   /// Returns the previous consecutive position.
+  ///
+  /// - Precondition: The result is within the bounds of the same allocation.
   public func predecessor() -> ${Self} {
     return self - 1
   }
 
   /// Returns `end - self`.
-  public func distance(to x: ${Self}) -> Int {
-    return x - self
+  ///
+  /// - Precondition: The result is within the bounds of the same allocation.
+  public func distance(to end: ${Self}) -> Int {
+    return end - self
   }
 
   /// Returns `self + n`.
+  ///
+  /// - Precondition: The result is within the bounds of the same allocation.
   public func advanced(by n: Int) -> ${Self} {
     return self + n
   }
@@ -478,39 +486,43 @@ extension ${Self} : CustomPlaygroundQuickLookable {
   }
 }
 
-/// - Note: Strideable's implementation is potentially less efficient and cannot
-///   handle misaligned pointers.
+// - Note: Strideable's implementation is potentially less efficient and cannot
+//   handle misaligned pointers.
 @_transparent
 public func == <Pointee>(
   lhs: ${Self}<Pointee>, rhs: ${Self}<Pointee>
 ) -> Bool {
   return Bool(Builtin.cmp_eq_RawPointer(lhs._rawValue, rhs._rawValue))
 }
 
-/// - Note: Strideable's implementation is potentially less efficient and cannot
-///   handle misaligned pointers.
-///
-/// - Note: This is an unsigned comparison unlike Strideable's implementation.
+// - Note: Strideable's implementation is potentially less efficient and cannot
+//   handle misaligned pointers.
+//
+// - Note: This is an unsigned comparison unlike Strideable's implementation.
 @_transparent
 public func < <Pointee>(lhs: ${Self}<Pointee>, rhs: ${Self}<Pointee>) -> Bool {
   return Bool(Builtin.cmp_ult_RawPointer(lhs._rawValue, rhs._rawValue))
 }
 
-/// - Note: The following family of operator overloads are redundant
-///   with Strideable. However, optimizer improvements are needed
-///   before they can be removed without affecting performance.
+// - Note: The following family of operator overloads are redundant
+//   with Strideable. However, optimizer improvements are needed
+//   before they can be removed without affecting performance.
+
+/// - Precondition: The result is within bounds of the same allocation.
 @_transparent
 public func + <Pointee>(lhs: ${Self}<Pointee>, rhs: Int) -> ${Self}<Pointee> {
   return ${Self}(Builtin.gep_Word(
     lhs._rawValue, rhs._builtinWordValue, Pointee.self))
 }
 
+/// - Precondition: The result is within the bounds of the same allocation.
 @_transparent
 public func + <Pointee>(lhs: Int,
            rhs: ${Self}<Pointee>) -> ${Self}<Pointee> {
   return rhs + lhs
 }
 
+/// - Precondition: The result is within the bounds of the same allocation.
 @_transparent
 public func - <Pointee>(lhs: ${Self}<Pointee>, rhs: Int) -> ${Self}<Pointee> {
   return lhs + -rhs
@@ -524,11 +536,13 @@ public func - <Pointee>(lhs: ${Self}<Pointee>, rhs: ${Self}<Pointee>) -> Int {
     / MemoryLayout<Pointee>.stride
 }
 
+/// - Precondition: The result is within the bounds of the same allocation.
 @_transparent
 public func += <Pointee>(lhs: inout ${Self}<Pointee>, rhs: Int) {
   lhs = lhs + rhs
 }
 
+/// - Precondition: The result is within the bounds of the same allocation.
 @_transparent
 public func -= <Pointee>(lhs: inout ${Self}<Pointee>, rhs: Int) {
   lhs = lhs - rhs