Add doc comments for some concrete SIMD overloads. (swiftlang#81890)

Also removed concrete SIMDMask(lowHalf:highHalf:) init, as there is no
corresponding generic operation; it was added in error.

Author: stephentyrone

stdlib/public/core/SIMDFloatConcreteOperations.swift.gyb

@@ -34,6 +34,15 @@ extension SIMD${n} where Scalar == ${Scalar} {
     _storage = ${Scalar}.SIMD${storageN}Storage(_builtin)
   }
 
+  /// A vector with the specified scalar in all lanes.
+  ///
+  /// Equivalent to:
+  /// ```
+  /// var result = SIMD${n}<${Scalar}>()
+  /// for i in result.indices {
+  ///   result[i] = scalar
+  /// }
+  /// ```
   @_alwaysEmitIntoClient @_transparent
   public init(repeating scalar: ${Scalar}) {
     let asVector = Builtin.insertelement_${Builtin}_FPIEEE${bits}_Int32(
@@ -52,6 +61,16 @@ extension SIMD${n} where Scalar == ${Scalar} {
   }
 
 %  if n >= 4:
+  /// A vector formed by concatenating lowHalf and highHalf.
+  ///
+  /// Equivalent to:
+  /// ```
+  /// var result = SIMD${n}<${Scalar}>()
+  /// for i in 0..<${n//2} {
+  ///   result[i] = lowHalf[i]
+  ///   result[${n//2}+i] = highHalf[i]
+  /// }
+  /// ```
   @_alwaysEmitIntoClient @_transparent
   public init(
     lowHalf: SIMD${n//2}<${Scalar}>,

stdlib/public/core/SIMDIntegerConcreteOperations.swift.gyb

@@ -31,6 +31,15 @@ extension SIMD${n} where Scalar == ${Scalar} {
     _storage = ${Scalar}.SIMD${storageN}Storage(_builtin)
   }
 
+  /// A vector with the specified scalar in all lanes.
+  ///
+  /// Equivalent to:
+  /// ```
+  /// var result = SIMD${n}<${Scalar}>()
+  /// for i in result.indices {
+  ///   result[i] = scalar
+  /// }
+  /// ```
   @_alwaysEmitIntoClient @_transparent
   public init(repeating scalar: ${Scalar}) {
     let asVector = Builtin.insertelement_${Builtin}_Int${int.bits}_Int32(
@@ -49,6 +58,16 @@ extension SIMD${n} where Scalar == ${Scalar} {
   }
 
 %  if n >= 4:
+  /// A vector formed by concatenating lowHalf and highHalf.
+  ///
+  /// Equivalent to:
+  /// ```
+  /// var result = SIMD${n}<${Scalar}>()
+  /// for i in 0..<${n//2} {
+  ///   result[i] = lowHalf[i]
+  ///   result[${n//2}+i] = highHalf[i]
+  /// }
+  /// ```
   @_alwaysEmitIntoClient @_transparent
   public init(
     lowHalf: SIMD${n//2}<${Scalar}>,

stdlib/public/core/SIMDMaskConcreteOperations.swift.gyb

@@ -36,19 +36,6 @@ extension SIMDMask where Storage == ${Vector} {
     _storage = ${Vector}(repeating: scalar ? -1 : 0)
   }
 
-%  if n >= 4:
-  @_alwaysEmitIntoClient @_transparent
-  public init(
-    lowHalf: SIMDMask<SIMD${n//2}<${Scalar}>>,
-    highHalf: SIMDMask<SIMD${n//2}<${Scalar}>>
-  ) {
-    _storage = ${Vector}(
-      lowHalf: lowHalf._storage,
-      highHalf: highHalf._storage
-    )
-  }
-  
-%  end
   @_alwaysEmitIntoClient
   internal static var allTrue: Self {
     let zero = ${Vector}()

stdlib/public/core/SIMDVector.swift

@@ -111,7 +111,15 @@ extension SIMD {
     return 0 ..< scalarCount
   }
 
-  /// A vector with the specified value in all lanes.
+  /// A vector with the specified scalar in all lanes.
+  ///
+  /// Equivalent to:
+  /// ```
+  /// var result = Self()
+  /// for i in result.indices {
+  ///   result[i] = scalar
+  /// }
+  /// ```
   @_transparent
   public init(repeating value: Scalar) {
     self.init()

stdlib/public/core/SIMDVectorTypes.swift.gyb

@@ -88,7 +88,16 @@ public struct SIMD${n}<Scalar>: SIMD where Scalar: SIMDScalar {
 %  end
 % end
 % if n >= 4:
-  /// Creates a new vector from two half-length vectors.
+  /// A vector formed by concatenating lowHalf and highHalf.
+  ///
+  /// Equivalent to:
+  /// ```
+  /// var result = SIMD${n}<Scalar>()
+  /// for i in 0..<${n//2} {
+  ///   result[i] = lowHalf[i]
+  ///   result[${n//2}+i] = highHalf[i]
+  /// }
+  /// ```
   @_transparent
   public init(lowHalf: SIMD${n//2}<Scalar>, highHalf: SIMD${n//2}<Scalar>) {
     self.init()

test/stdlib/SIMDMaskInitializers.swift.gyb

@@ -34,51 +34,3 @@ func repeating${n}_mask${bits}(_ scalar: Bool) -> SIMDMask<SIMD${n}<Int${bits}>>
 %  end
 % end
 %end
-
-func concat8x8(_ a: SIMDMask<SIMD8<Int8>>, _ b: SIMDMask<SIMD8<Int8>>) -> SIMDMask<SIMD16<Int8>> {
-  SIMDMask(lowHalf: a, highHalf: b)
-}
-// CHECK: s20SIMDMaskInitializers9concat8x8ys0A0Vys6SIMD16Vys4Int8VGGADys5SIMD8VyAHGG_ANtF:
-// CHECKO-arm64-NEXT: mov.d v0[1], v1[0]
-// CHECKO-arm64-NEXT: ret
-// CHECKO-x86_64: punpcklqdq
-
-func concat16x8(_ a: SIMDMask<SIMD16<Int8>>, _ b: SIMDMask<SIMD16<Int8>>) -> SIMDMask<SIMD32<Int8>> {
-  SIMDMask(lowHalf: a, highHalf: b)
-}
-// CHECK: s20SIMDMaskInitializers10concat16x8ys0A0Vys6SIMD32Vys4Int8VGGADys6SIMD16VyAHGG_ANtF:
-// CHECKO-arm64-NEXT: ret
-
-func concat4x16(_ a: SIMDMask<SIMD4<Int16>>, _ b: SIMDMask<SIMD4<Int16>>) -> SIMDMask<SIMD8<Int16>> {
-  SIMDMask(lowHalf: a, highHalf: b)
-}
-// CHECK: s20SIMDMaskInitializers10concat4x16ys0A0Vys5SIMD8Vys5Int16VGGADys5SIMD4VyAHGG_ANtF:
-// CHECKO-arm64-NEXT: mov.d v0[1], v1[0]
-// CHECKO-arm64-NEXT: ret
-// CHECKO-x86_64: punpcklqdq
-
-func concat8x16(_ a: SIMDMask<SIMD8<Int16>>, _ b: SIMDMask<SIMD8<Int16>>) -> SIMDMask<SIMD16<Int16>> {
-  SIMDMask(lowHalf: a, highHalf: b)
-}
-// CHECK: s20SIMDMaskInitializers10concat8x16ys0A0Vys6SIMD16Vys5Int16VGGADys5SIMD8VyAHGG_ANtF:
-// CHECKO-arm64-NEXT: ret
-
-func concat2x32(_ a: SIMDMask<SIMD2<Int32>>, _ b: SIMDMask<SIMD2<Int32>>) -> SIMDMask<SIMD4<Int32>> {
-  SIMDMask(lowHalf: a, highHalf: b)
-}
-// CHECK: s20SIMDMaskInitializers10concat2x32ys0A0Vys5SIMD4Vys5Int32VGGADys5SIMD2VyAHGG_ANtF:
-// CHECKO-arm64-NEXT: mov.d v0[1], v1[0]
-// CHECKO-arm64-NEXT: ret
-// CHECKO-x86_64: punpcklqdq
-
-func concat4x32(_ a: SIMDMask<SIMD4<Int32>>, _ b: SIMDMask<SIMD4<Int32>>) -> SIMDMask<SIMD8<Int32>> {
-  SIMDMask(lowHalf: a, highHalf: b)
-}
-// CHECK: s20SIMDMaskInitializers10concat4x32ys0A0Vys5SIMD8Vys5Int32VGGADys5SIMD4VyAHGG_ANtF:
-// CHECKO-arm64-NEXT: ret
-
-func concat2x64(_ a: SIMDMask<SIMD2<Int64>>, _ b: SIMDMask<SIMD2<Int64>>) -> SIMDMask<SIMD4<Int64>> {
-  SIMDMask(lowHalf: a, highHalf: b)
-}
-// CHECK: s20SIMDMaskInitializers10concat2x64ys0A0Vys5SIMD4Vys5Int64VGGADys5SIMD2VyAHGG_ANtF:
-// CHECKO-arm64-NEXT: ret