Update doc comments on non-mutating API to use proper wording. (tensorflow#183)

Fixes a part of tensorflow#160.

Author: Shashi456

Sources/TensorFlow/Operators/Basic.swift

@@ -315,7 +315,7 @@ public extension Tensor {
         return transposed(withPermutations: Tensor<Int32>(defaultPermutations))
     }
 
-    /// Concatenates tensors along the specified axis.
+    /// Returns a concatenated tensor along the specified axis.
     /// - Precondition: The tensors must have the same dimensions, except for the
     ///   specified axis.
     /// - Precondition: The axis must be in the range `-rank..<rank`.
@@ -336,7 +336,7 @@ public extension Tensor {
         return lhs.concatenated(with: rhs)
     }
 
-    /// Gathers slices of this tensor at `indices` along the `axis` dimension.
+    /// Returns a tensor by gathering slices of the input at `indices` along the `axis` dimension
     ///
     /// For 0-D (scalar) `indices`:
     /// ```
@@ -387,7 +387,7 @@ public extension Tensor {
         return Raw.gatherV2(params: self, indices: indices, axis: Tensor<Int32>(Int32(axis)))
     }
 
-    /// Gathers values from this tensor according to the provided boolean mask.
+    /// Returns a tensor by gathering the values after applying the provided boolean mask to the input.
     ///
     /// For example:
     /// ```

Sources/TensorFlow/Operators/Comparison.swift

@@ -20,80 +20,80 @@ infix operator .==: ComparisonPrecedence
 infix operator .!=: ComparisonPrecedence
 
 public extension Tensor where Scalar: Numeric & Comparable {
-    /// Computes `lhs < rhs` element-wise and returns a `Tensor` of Boolean /// scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs < rhs` element-wise.
     @inlinable
     static func .< (lhs: Tensor, rhs: Tensor) -> Tensor<Bool> {
         return Raw.less(lhs, rhs)
     }
 
-    /// Computes `lhs <= rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs <= rhs` element-wise.
     @inlinable
     static func .<= (lhs: Tensor, rhs: Tensor) -> Tensor<Bool> {
         return Raw.lessEqual(lhs, rhs)
     }
 
-    /// Computes `lhs > rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs > rhs` element-wise.
     @inlinable
     static func .> (lhs: Tensor, rhs: Tensor) -> Tensor<Bool> {
         return Raw.greater(lhs, rhs)
     }
 
-    /// Computes `lhs >= rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs >= rhs` element-wise.
     @inlinable
     static func .>= (lhs: Tensor, rhs: Tensor) -> Tensor<Bool> {
         return Raw.greaterEqual(lhs, rhs)
     }
 
-    /// Computes `lhs < rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs < rhs` element-wise.
     /// - Note: `.<` supports broadcasting.
     @inlinable
     static func .< (lhs: Scalar, rhs: Tensor) -> Tensor<Bool> {
         return Raw.less(Tensor(lhs), rhs)
     }
 
-    /// Computes `lhs <= rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs <= rhs` element-wise.
     /// - Note: `.<=` supports broadcasting.
     @inlinable
     static func .<= (lhs: Scalar, rhs: Tensor) -> Tensor<Bool> {
         return Raw.lessEqual(Tensor(lhs), rhs)
     }
 
-    /// Computes `lhs > rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs > rhs` element-wise.
     /// - Note: `.>` supports broadcasting.
     @inlinable
     static func .> (lhs: Scalar, rhs: Tensor) -> Tensor<Bool> {
         return Raw.greater(Tensor(lhs), rhs)
     }
 
-    /// Computes `lhs >= rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs >= rhs` element-wise.
     /// - Note: `.>=` supports broadcasting.
     @inlinable
     static func .>= (lhs: Scalar, rhs: Tensor) -> Tensor<Bool> {
         return Raw.greaterEqual(Tensor(lhs), rhs)
     }
 
-    /// Computes `lhs < rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs < rhs` element-wise.
     /// - Note: `.<` supports broadcasting.
     @inlinable
     static func .< (lhs: Tensor, rhs: Scalar) -> Tensor<Bool> {
         return Raw.less(lhs, Tensor(rhs))
     }
 
-    /// Computes `lhs <= rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs <= rhs` element-wise.
     /// - Note: `.<=` supports broadcasting.
     @inlinable
     static func .<= (lhs: Tensor, rhs: Scalar) -> Tensor<Bool> {
         return Raw.lessEqual(lhs, Tensor(rhs))
     }
 
-    /// Computes `lhs > rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs > rhs` element-wise.
     /// - Note: `.>` supports broadcasting.
     @inlinable
     static func .> (lhs: Tensor, rhs: Scalar) -> Tensor<Bool> {
         return Raw.greater(lhs, Tensor(rhs))
     }
 
-    /// Computes `lhs >= rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs >= rhs` element-wise.
     /// - Note: `.>=` supports broadcasting.
     @inlinable
     static func .>= (lhs: Tensor, rhs: Scalar) -> Tensor<Bool> {
@@ -162,43 +162,42 @@ public extension Tensor where Scalar: Numeric & Comparable {
 }
 
 public extension Tensor where Scalar: Equatable {
-    /// Computes `lhs != rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs == rhs` element-wise.
     /// - Note: `.==` supports broadcasting.
     @inlinable
     static func .== (lhs: Tensor, rhs: Tensor) -> Tensor<Bool> {
         return Raw.equal(lhs, rhs)
     }
 
-    /// Computes `lhs != rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs != rhs` element-wise.
     /// - Note: `.!=` supports broadcasting.
     @inlinable
     static func .!= (lhs: Tensor, rhs: Tensor) -> Tensor<Bool> {
         return Raw.notEqual(lhs, rhs)
     }
 
-    /// Computes `lhs == rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs == rhs` element-wise.
     /// - Note: `.==` supports broadcasting.
     @inlinable
     static func .== (lhs: Scalar, rhs: Tensor) -> Tensor<Bool> {
         return Tensor(lhs) .== rhs
     }
 
-    /// Computes `lhs != rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs != rhs` element-wise.
     /// - Note: `.!=` supports broadcasting.
     @inlinable
     static func .!= (lhs: Scalar, rhs: Tensor) -> Tensor<Bool> {
         return Tensor(lhs) .!= rhs
     }
 
-    /// Computes `lhs == rhs` element-wise and returns a `Tensor` of Boolean
-    /// scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs == rhs` element-wise.
     /// - Note: `.==` supports broadcasting.
     @inlinable
     static func .== (lhs: Tensor, rhs: Scalar) -> Tensor<Bool> {
         return lhs .== Tensor(rhs)
     }
 
-    /// Computes `lhs != rhs` element-wise and returns a `Tensor` of Boolean scalars.
+    /// Returns a tensor of Boolean scalars by computing `lhs != rhs` element-wise.
     /// - Note: `.!=` supports broadcasting.
     @inlinable
     static func .!= (lhs: Tensor, rhs: Scalar) -> Tensor<Bool> {
@@ -209,7 +208,7 @@ public extension Tensor where Scalar: Equatable {
 // TODO: infix operator ≈: ComparisonPrecedence
 
 public extension Tensor where Scalar: FloatingPoint & Equatable {
-    /// Returns a `Tensor` of Boolean values indicating whether the elements of `self` are
+    /// Returns a tensor of Boolean values indicating whether the elements of `self` are
     /// approximately equal to those of `other`.
     @inlinable
     func elementsApproximatelyEqual(

Sources/TensorFlow/Operators/Math.swift

@@ -68,44 +68,41 @@ public extension Tensor where Scalar: Numeric {
         return lhs - Tensor(rhs)
     }
 
-    /// Adds two tensors and stores the result in the left-hand-side variable.
+    /// Returns the tensor produced by adding the two tensors.
     /// - Note: `+=` supports broadcasting.
     @inlinable
     static func += (lhs: inout Tensor, rhs: Tensor) {
         lhs = lhs + rhs
     }
 
-    /// Adds the scalar to every scalar of the tensor and stores the result in the left-hand-side
-    /// variable.
+    /// Returns the scalar by adding it to every scalar of the tensor.
     @inlinable
     static func += (lhs: inout Tensor, rhs: Scalar) {
         lhs = lhs + rhs
     }
 
-    /// Subtracts the second tensor from the first and stores the result in the left-hand-side
-    /// variable.
+    /// Returns the tensor by subracting the second tensor from the first.
     /// - Note: `-=` supports broadcasting.
     @inlinable
     static func -= (lhs: inout Tensor, rhs: Tensor) {
         lhs = lhs - rhs
     }
 
-    /// Subtracts the scalar from every scalar of the tensor and stores the result in the
-    /// left-hand-side variable.
+    /// Returns the scalar by subtracting every scalar of the tensor from it.
     @inlinable
     static func -= (lhs: inout Tensor, rhs: Scalar) {
         lhs = lhs - rhs
     }
 
-    /// Multiplies two tensors and produces their product.
+    /// Returns the tensor produced by multiplying the two tensors.
     /// - Note: `*` supports broadcasting.
     @inlinable
     @differentiable(vjp: _vjpMultiply(lhs:rhs:) where Scalar: TensorFlowFloatingPoint)
     static func * (lhs: Tensor, rhs: Tensor) -> Tensor {
         return Raw.mul(lhs, rhs)
     }
 
-    /// Multiplies the scalar with every scalar of the tensor and produces the product.
+    ///  Returns the scalar by multiplying it with every scalar of the tensor.
     @inlinable
     @differentiable(vjp: _vjpMultiply(lhs:rhs:) where Scalar: TensorFlowFloatingPoint)
     static func * (lhs: Scalar, rhs: Tensor) -> Tensor {
@@ -119,14 +116,14 @@ public extension Tensor where Scalar: Numeric {
         return lhs * Tensor(rhs)
     }
 
-    /// Multiplies two tensors and stores the result in the left-hand-side variable.
+    /// Returns the tensor produced by multiplying the two tensors.
     /// - Note: `*=` supports broadcasting.
     @inlinable
     static func *= (lhs: inout Tensor, rhs: Tensor) {
         lhs = lhs * rhs
     }
 
-    /// Multiplies the tensor with the scalar, broadcasting the scalar, and stores the result in the
+    /// Returns the tensor by multiplying it with the scalar, broadcasting the scalar.
     /// left-hand-side variable.
     @inlinable
     static func *= (lhs: inout Tensor, rhs: Scalar) {

Sources/TensorFlow/Operators/NN.swift

@@ -17,7 +17,7 @@
 //===------------------------------------------------------------------------------------------===//
 
 public extension Tensor where Scalar: TensorFlowFloatingPoint {
-    /// Computes the batch normalized tensor along the specified axis.
+    /// Returns a tensor computed from batch-normalizing the input along the specified axis.
     ///
     /// Specifically, returns `(self - mu) / (var + epsilon) * gamma + beta` where `mu` and `var`
     /// are respectively the mean and variance of `self` along `axis`.