1 files changed, 23 insertions, 22 deletions

diff --git a/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java b/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java
index d650b88f202..ac9dc4e4eca 100644
--- a/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java
+++ b/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java
@@ -40,7 +40,7 @@ import static com.yahoo.tensor.functions.ScalarFunctions.Hamming;
  * A multidimensional array which can be used in computations.
  * <p>
  * A tensor consists of a set of <i>dimension</i> names and a set of <i>cells</i> containing scalar <i>values</i>.
- * Each cell is is identified by its <i>address</i>, which consists of a set of dimension-label pairs which defines
+ * Each cell is identified by its <i>address</i>, which consists of a set of dimension-label pairs which defines
  * the location of that cell. Both dimensions and labels are string on the form of an identifier or integer.
  * <p>
  * The size of the set of dimensions of a tensor is called its <i>rank</i>.
@@ -55,7 +55,9 @@ import static com.yahoo.tensor.functions.ScalarFunctions.Hamming;
  * @author bratseth
  */
 public interface Tensor {
-    int INVALID_INDEX = -1;
+
+    /** The constant signaling a nonexisting value in operations addressing tensor values by index. */
+    int invalidIndex = -1;
 
     // ----------------- Accessors
 
@@ -65,25 +67,24 @@ public interface Tensor {
     default boolean isEmpty() { return size() == 0; }
 
     /**
-     *  Returns the number of cells in this.
-     *  Allows for very large tensors, but if you only handle size in the int range
-     *  prefer sizeAsInt().
-     **/
+     *  Returns the number of cells in this, allowing for very large tensors.
+     *  Prefer sizeAsInt in implementations that cannot handle sizes outside the int range.
+     */
     default long size() {
         return sizeAsInt();
     }
 
     /**
-     * Safe way to get size as an int and detect when not possible.
-     * Prefer this over size() as
-     * @return size() as an int
+     * Returns the size of this as an int or throws an exception if it is too large to fit in an int.
+     * Prefer this over size() with implementations that only handle sizes in the int range.
+     *
+     * @throws IndexOutOfBoundsException if the size is too large to fit in an int
      */
     default int sizeAsInt() {
-        long sz = size();
-        if (sz > Integer.MAX_VALUE) {
-            throw new IndexOutOfBoundsException("size = " + sz + ", which is too large to fit in an int");
-        }
-        return (int) sz;
+        long size = size();
+        if (size > Integer.MAX_VALUE)
+            throw new IndexOutOfBoundsException("size = " + size + ", which is too large to fit in an int");
+        return (int) size;
     }
 
     /** Returns the value of a cell, or 0.0 if this cell does not exist */
@@ -91,7 +92,8 @@ public interface Tensor {
 
     /** Returns true if this cell exists */
     boolean has(TensorAddress address);
-    /** null = no value present. More efficient that if (t.has(key)) t.get(key) */
+
+    /** Returns the value at this address, or null of it does not exist. */
     Double getAsDouble(TensorAddress address);
 
     /**
@@ -132,7 +134,7 @@ public interface Tensor {
     /**
      * Returns a new tensor where existing cells in this tensor have been
      * modified according to the given operation and cells in the given map.
-     * Cells in the map outside of existing cells are thus ignored.
+     * Cells in the map outside existing cells are thus ignored.
      *
      * @param op the modifying function
      * @param cells the cells to modify
@@ -151,9 +153,9 @@ public interface Tensor {
 
     /**
      * Returns a new tensor where existing cells in this tensor have been
-     * removed according to the given set of addresses. Only valid for sparse
+     * removed according to the given set of addresses. Only valid for mapped
      * or mixed tensors. For mixed tensors, addresses are assumed to only
-     * contain the sparse dimensions, as the entire dense subspace is removed.
+     * contain the mapped dimensions, as the entire indexed subspace is removed.
      *
      * @param addresses list of addresses to remove
      * @return a new tensor where cells have been removed
@@ -503,11 +505,10 @@ public interface Tensor {
         public TensorAddress getKey() { return address; }
 
         /**
-         * Returns the direct index which can be used to locate this cell, or -1 if not available.
-         * This is for optimizations mapping between tensors where this is possible without creating a
-         * TensorAddress.
+         * Returns the direct index which can be used to locate this cell, or Tensor.invalidIndex if not available.
+         * This is for optimizations mapping between tensors where this is possible without creating a TensorAddress.
          */
-        long getDirectIndex() { return INVALID_INDEX; }
+        long getDirectIndex() { return invalidIndex; }
 
         /** Returns the value as a double */
         @Override