Rectify documentation based on PR review

Author: karllessard

tensorflow-core/tensorflow-core-api/src/gen/annotations/org/tensorflow/op/Ops.java

@@ -1070,17 +1070,6 @@ public <T extends TNumber> Bucketize bucketize(Operand<T> input, List<Float> bou
     return Bucketize.create(scope, input, boundaries);
   }
 
-  /**
-   * Capture a {@code tensor} by making a constant copy of it.
-   *
-   * @param scope is a scope used to add the underlying operation.
-   * @param tensor a Tensor holding the constant value
-   * @return a constant of the same data type as `tensor`
-   */
-  public <T extends TType> Constant<T> capture(T tensor) {
-    return Constant.create(scope, tensor);
-  }
-
   /**
    * Clips tensor values to a specified min and max.
    *  <p>
@@ -1876,6 +1865,20 @@ public <T extends TType> Constant<T> constant(DataType<T> type, Shape shape,
     return Constant.tensorOf(scope, type, shape, data);
   }
 
+  /**
+   * Create a constant by making an immutable copy of {@code tensor}.
+   *
+   *  <p>Note: this endpoint cannot be simply called {@code constant} since it will conflict with
+   *  other endpoints accepting an NdArray in parameter {e.g. {@link #tensorOf(Scope, FloatNdArray)}}.
+   *
+   * @param scope is a scope used to add the underlying operation.
+   * @param tensor a Tensor holding the constant value
+   * @return a constant of the same data type as `tensor`
+   */
+  public <T extends TType> Constant<T> constantOf(T tensor) {
+    return Constant.create(scope, tensor);
+  }
+
   /**
    * This op consumes a lock created by `MutexLock`.
    *  <p>

tensorflow-core/tensorflow-core-api/src/main/java/org/tensorflow/DataType.java

@@ -36,6 +36,10 @@ public interface TensorMapper<T> {
     /**
      * Maps the tensor memory to a n-dimensional typed data space.
      *
+     * <p>This method is designed to be invoked internally by this library only, in order to pass the
+     * native handle of {@code tensor} as {@code nativeHandle} (and since only classes from the
+     * {@code org.tensorflow} package can retrieve such handle).
+     *
      * @param tensor the tensor to map in its raw nature
      * @param nativeHandle native handle of the tensor
      * @return a typed tensor of type {@code T}

tensorflow-core/tensorflow-core-api/src/main/java/org/tensorflow/RawTensor.java

@@ -29,25 +29,18 @@
 import org.tensorflow.types.family.TType;
 
 /**
- * A tensor which memory has not been mapped.
+ * A tensor which memory has not been mapped to a data space directly accessible from the JVM.
  *
  * <p>A raw tensor is a minimalist representation of a tensor allocated in native memory by the
  * TensorFlow runtime library and it controls its lifetime within the current process. The data
  * is represented by a flat {@link ByteDataBuffer buffer of bytes}, until it is mapped in a
  * n-dimensional typed space by a {@link TType typed tensor}.</p>
  *
  * <p>Instances of a RawTensor are <b>not</b> thread-safe and their resource must be released
- * by calling {@link #close()} explicitly or implicitly (try-with-resources).</p>
+ * by calling {@link #close()} explicitly or implicitly via try-with-resources.</p>
  */
 public final class RawTensor implements Tensor {
 
-  /**
-   * Returns a typed version of this tensor
-   */
-  TType asTypedTensor() {
-    return dtype.map(this);
-  }
-
   @Override
   public DataType<?> dataType() {
     return dtype;
@@ -152,13 +145,28 @@ static RawTensor fromHandle(TF_Tensor handle, EagerSession session) {
   }
 
   /**
-   * @return native handle to this tensor
+   * Returns the native handle to this tensor
    * @throws IllegalStateException if tensor has been closed
    */
   TF_Tensor nativeHandle() {
     return requireHandle(tensorHandle);
   }
 
+  /**
+   * Returns a typed reference to this tensor
+   *
+   * <p>In some cases, it is more useful to keep a typed reference to a tensor rather than its raw
+   * nature to prevent mapping its memory on every access (e.g. when calling {@link Operand#asTensor()}).
+   *
+   * @param <T> type of the tensor (must be compatible with the internal representation of this tensor,
+   *            as indicated by {@link #dataType()})
+   * @return typed reference to this tensor
+   * @throws ClassCastException if {@code T} is not compatible type with {@link #dataType()}
+   */
+  <T extends TType> T asTypedTensor() {
+    return (T)dtype.map(this);
+  }
+
   private static TF_Tensor requireHandle(TF_Tensor handle) {
     if (handle == null || handle.isNull()) {
       throw new IllegalStateException("close() was called on the Tensor");

tensorflow-core/tensorflow-core-api/src/main/java/org/tensorflow/Tensor.java

@@ -46,9 +46,8 @@
  * try (Tensor t = Tensor.of(...)) {
  *   doSomethingWith(t);
  * }
- *
- * <p>Instances of a Tensor are <b>not</b> thread-safe.
  * }</pre>
+ * <p>Instances of a Tensor are <b>not</b> thread-safe.
  */
 public interface Tensor extends Shaped, AutoCloseable {
 
@@ -88,7 +87,7 @@ static <T extends TType> T of(DataType<T> dtype, Shape shape) {
   static <T extends TType> T of(DataType<T> dtype, Shape shape, long size) {
     RawTensor tensor = RawTensor.allocate(dtype, shape, size);
     try {
-      return dtype.map(tensor);
+      return tensor.asTypedTensor();
     } catch (Exception e) {
       tensor.close();
       throw e;
@@ -130,7 +129,7 @@ static <T extends TType> T of(DataType<T> dtype, Shape shape, Consumer<T> dataIn
    * size for the tensor is explicitly set instead of being computed from the datatype and shape.
    *
    * <p>This could be useful for tensor types that stores data but also metadata in the tensor memory,
-   * such as lookup table in a tensor of strings.
+   * such as the lookup table in a tensor of strings.
    *
    * @param <T> the tensor element type
    * @param dtype datatype of the tensor
@@ -148,7 +147,7 @@ static <T extends TType> T of(DataType<T> dtype, Shape shape, long size, Consume
     try {
       dataInitializer.accept(tensor);
       return tensor;
-    } catch (Throwable t) {
+    } catch (Exception t) {
       tensor.close();
       throw t;
     }

tensorflow-core/tensorflow-core-api/src/main/java/org/tensorflow/op/core/Constant.java

@@ -1278,13 +1278,16 @@ public static Constant<TInt64> tensorOf(Scope scope, Shape shape) {
   }
 
   /**
-   * Capture a {@code tensor} by making a constant copy of it.
+   * Create a constant by making an immutable copy of {@code tensor}.
+   *
+   * <p>Note: this endpoint cannot be simply called {@code constant} since it will conflict with
+   * other endpoints accepting an NdArray in parameter {e.g. {@link #tensorOf(Scope, FloatNdArray)}}.
    *
    * @param scope is a scope used to add the underlying operation.
    * @param tensor a Tensor holding the constant value
    * @return a constant of the same data type as `tensor`
    */
-  @Endpoint(name = "capture") // Cannot be "constant" since it will conflict with other endpoints accepting an NdArray
+  @Endpoint(name = "constantOf")
   public static <T extends TType> Constant<T> create(Scope scope, T tensor) {
     return new Constant<>(
         scope

tensorflow-core/tensorflow-core-api/src/main/java/org/tensorflow/types/family/TType.java

@@ -22,12 +22,12 @@
 /**
  * Common interface for all typed tensors.
  *
- * <p>Typed tensors wraps a {@link RawTensor} by mapping their native memory to a n-dimensional
- * data space allowing direct I/O access from the JVM.</p>
+ * <p>Typed tensors wrap a {@link org.tensorflow.RawTensor RawTensor} by mapping their native memory
+ * to a n-dimensional data space allowing direct I/O access from the JVM.</p>
  *
  * <p>Subinterfaces of {@code TType} are propagated as a generic parameter to various entities of
  * TensorFlow to identify the type of the tensor they carry. For example, a
- * {@link org.tensorflow.Operand Operand<TFloat32>} is an operand which outputs is a 32-bit floating
+ * {@link org.tensorflow.Operand Operand<TFloat32>} is an operand which outputs a 32-bit floating
  * point tensor. This parameter ensure type-compatibility between operands of a computation at
  * compile-time. For example:
  *
@@ -41,6 +41,22 @@
  * tf.math.add(c1, c2);  // OK
  * tf.math.add(c1, c3);  // Compilation failure
  * }</pre>
+ *
+ * <p>Even if all typed tensors implements somehow {@link org.tensorflow.ndarray.NdArray NdArray}
+ * to provide access to their data, {@code TType} deliberately does not extend directly from this
+ * interface, for the following reasons:
+ * <ul>
+ *   <li>Implementing {@code NdArray} at this level could only expose boxed-type accessors, which
+ *   are less performant than their primitive equivalent, only exposed by subinterfaces of
+ *   {@code NdArray} (e.g. {@code FloatNdArray}).
+ *   </li>
+ *   <li>{@code TType} would need to carry a new generic parameter for typing the {@code NdArray},
+ *   which will increase the verbosity in the signature of any method accepting or returning
+ *   an instance of this interface, which is very common.
+ *   </li>
+ * </ul>
+ * Therefore, enforcing the user to cast a reference of {@code TType} in a concrete tensor type before
+ * accessing its data guarantees better performance and improves readability.
  */
 public interface TType extends Tensor {
 

tensorflow-core/tensorflow-core-api/src/test/java/org/tensorflow/op/core/ConstantTest.java

@@ -158,7 +158,7 @@ public void createFromTensorsInEagerMode() throws IOException {
       assertEquals(c1.asTensor(), t);
 
       // A different endpoint for capturing a tensor as a constant, which supports all data types
-      Constant<TInt32> c2 = tf.capture(t);
+      Constant<TInt32> c2 = tf.constantOf(t);
       assertEquals(c2.asTensor(), t);
       assertEquals(c1.asTensor(), c2.asTensor());
 

tensorflow-core/tensorflow-core-api/src/test/java/org/tensorflow/op/core/GradientsTest.java

@@ -48,7 +48,7 @@ public void createGradients() {
       assertEquals(2, grads.dy().size());
 
       try (TFloat32 c = TFloat32.scalarOf(3.0f);
-          AutoCloseableList<?> outputs =
+          AutoCloseableList<Tensor> outputs =
               new AutoCloseableList<>(
                   sess.runner().feed(x, c).fetch(grads.dy(0)).fetch(grads.dy(1)).run())) {
 
@@ -75,7 +75,7 @@ public void createGradientsWithSum() {
       assertEquals(1, grads.dy().size());
 
       try (TFloat32 c = TFloat32.scalarOf(3.0f);
-          AutoCloseableList<?> outputs =
+          AutoCloseableList<Tensor> outputs =
               new AutoCloseableList<>(sess.runner().feed(x, c).fetch(grads.dy(0)).run())) {
 
         assertEquals(114.0f, ((TFloat32)outputs.get(0)).getFloat(), 0.0f);
@@ -101,7 +101,7 @@ public void createGradientsWithInitialValues() {
       assertEquals(1, grads1.dy().size());
 
       try (TFloat32 c = TFloat32.scalarOf(3.0f);
-          AutoCloseableList<?> outputs =
+          AutoCloseableList<Tensor> outputs =
               new AutoCloseableList<>(
                   sess.runner().feed(x, c).fetch(grads1.dy(0)).run())) {
 

tensorflow-core/tensorflow-core-api/src/test/java/org/tensorflow/types/NumericTypesTestBase.java

@@ -46,11 +46,11 @@ public void initializeTensorsWithZeros() {
 
       // Initialize tensor memory with zeros and take a snapshot
       data.scalars().forEach(scalar -> ((NdArray<U>)scalar).setObject(valueOf(0)));
-      Constant<T> x = tf.capture(tensor);
+      Constant<T> x = tf.constantOf(tensor);
 
       // Initialize the same tensor memory with ones and take a snapshot
       data.scalars().forEach(scalar -> ((NdArray<U>)scalar).setObject(valueOf(1)));
-      Constant<T> y = tf.capture(tensor);
+      Constant<T> y = tf.constantOf(tensor);
 
       // Subtract y from x and validate the result
       Sub<T> sub = tf.math.sub(x, y);
@@ -94,7 +94,7 @@ public void setAndCompute() {
       try (EagerSession session = EagerSession.create()) {
         Ops tf = Ops.create(session);
 
-        Add<T> add = tf.math.add(tf.capture(tensor), tf.capture(tensor));
+        Add<T> add = tf.math.add(tf.constantOf(tensor), tf.constantOf(tensor));
         NdArray<U> result = (NdArray<U>)add.asTensor();
 
         assertEquals(valueOf(0), result.getObject(0, 0));