Document the standard value order one place

4 files changed, 34 insertions, 36 deletions

diff --git a/vespajlib/src/main/java/com/yahoo/tensor/IndexedTensor.java b/vespajlib/src/main/java/com/yahoo/tensor/IndexedTensor.java
index 1da013de012..f5ef88016ac 100644
--- a/vespajlib/src/main/java/com/yahoo/tensor/IndexedTensor.java
+++ b/vespajlib/src/main/java/com/yahoo/tensor/IndexedTensor.java
@@ -16,7 +16,12 @@ import java.util.Set;
 import java.util.function.DoubleBinaryOperator;
 
 /**
- * An indexed (dense) tensor backed by an array.
+ * An indexed (dense) tensor.
+ * <p>
+ * Some methods on indexed tensors make use of a <b>standard value order</b>: Cells are ordered by increasing
+ * index where dimensions to the right are incremented before indexes to the left, where the order of dimensions are
+ * alphabetical by name. In consequence, tensor value ordering is independent of the order in which dimensions are
+ * specified, and the values of the right-most dimension are adjacent.
  *
  * @author bratseth
  */
@@ -34,9 +39,7 @@ public abstract class IndexedTensor implements Tensor {
     }
 
     /**
-     * Returns an iterator over the cells of this.
-     * Cells are returned in order of increasing indexes in each dimension, increasing
-     * indexes of later dimensions in the dimension type before earlier.
+     * Returns an iterator over the cells of this in the <i>standard value order</i>.
      */
     @Override
     public Iterator<Cell> cellIterator() {
@@ -58,11 +61,7 @@ public abstract class IndexedTensor implements Tensor {
         return new SubspaceIterator(iterateDimensions, startAddress, iterationSizes);
     }
 
-    /**
-     * Returns an iterator over the values of this.
-     * Values are returned in order of increasing indexes in each dimension, increasing
-     * indexes of later dimensions in the dimension type before earlier.
-     */
+    /** Returns an iterator over the values of this returned in the <i>standard value order</i> */
     @Override
     public Iterator<Double> valueIterator() {
         return new ValueIterator();
@@ -70,8 +69,8 @@ public abstract class IndexedTensor implements Tensor {
 
     /**
      * Returns an iterator over value iterators where the outer iterator is over each unique value of the dimensions
-     * given and the inner iterator is over each unique value of the rest of the dimensions, in the same order as
-     * other iterator.
+     * given and the inner iterator is over each unique value of the rest of the dimensions, in the
+     * <i>standard value order</i>
      *
      * @param dimensions the names of the dimensions of the superspace
      * @param sizes the size of each dimension in the space we are returning values for, containing
@@ -120,8 +119,7 @@ public abstract class IndexedTensor implements Tensor {
     }
 
     /**
-     * Returns the value at the given index as a double by direct lookup. Only use
-     * if you know the underlying data layout.
+     * Returns the value at the given <i>standard value order</i> index as a double.
      *
      * @param valueIndex the direct index into the underlying data.
      * @throws IllegalArgumentException if index is out of bounds
@@ -129,8 +127,7 @@ public abstract class IndexedTensor implements Tensor {
     public abstract double get(long valueIndex);
 
     /**
-     * Returns the value at the given index as a float by direct lookup. Only use
-     * if you know the underlying data layout.
+     * Returns the value at the given <i>standard value order</i> index as a float.
      *
      * @param valueIndex the direct index into the underlying data.
      * @throws IllegalArgumentException if index is out of bounds
@@ -310,7 +307,8 @@ public abstract class IndexedTensor implements Tensor {
          * Creates a builder initialized with the given values
          *
          * @param type the type of the tensor to build
-         * @param values the initial values of the tensor. This <b>transfers ownership</b> of the value array - it
+         * @param values the initial values of the tensor in the <i>standard value order</i>.
+         *               This <b>transfers ownership</b> of the value array - it
          *               must not be further mutated by the caller
          */
         public static Builder of(TensorType type, DimensionSizes sizes, float[] values) {
@@ -329,7 +327,8 @@ public abstract class IndexedTensor implements Tensor {
          * Creates a builder initialized with the given values
          *
          * @param type the type of the tensor to build
-         * @param values the initial values of the tensor. This <b>transfers ownership</b> of the value array - it
+         * @param values the initial values of the tensor in the <i>standard value order</i>.
+         *               This <b>transfers ownership</b> of the value array - it
          *               must not be further mutated by the caller
          */
         public static Builder of(TensorType type, DimensionSizes sizes, double[] values) {
@@ -411,10 +410,10 @@ public abstract class IndexedTensor implements Tensor {
 
         DimensionSizes sizes() { return sizes; }
 
-        /** Sets a value by its right-adjacent traversal position */
+        /** Sets a value by its <i>standard value order</i> index */
         public abstract void cellByDirectIndex(long index, double value);
 
-        /** Sets a value by its right-adjacent traversal position */
+        /** Sets a value by its <i>standard value order</i> index */
         public abstract void cellByDirectIndex(long index, float value);
 
     }
@@ -672,7 +671,7 @@ public abstract class IndexedTensor implements Tensor {
          * @param iterateDimensions the dimensions to iterate over, given as indexes in the dimension order of the
          *                          type of the tensor this iterates over. This iterator will iterate over these
          *                          dimensions to exhaustion in the order given (the first dimension index given is
-         *                          incremented  to exhaustion first (i.e is etc.), while other dimensions will be held
+         *                          incremented  to exhaustion first etc., while other dimensions will be held
          *                          at a constant position.
          *                          This may be any subset of the dimensions given by address and dimensionSizes.
          *                          This is treated as immutable.
diff --git a/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java b/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java
index 8b0aaa64551..afd82751137 100644
--- a/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java
+++ b/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java
@@ -295,21 +295,16 @@ public interface Tensor {
     // ----------------- serialization
 
     /**
-     * Returns this tensor on the form
-     * <code>{address1:value1,address2:value2,...}</code>
-     * where each address is on the form <code>{dimension1:label1,dimension2:label2,...}</code>,
-     * and values are numbers.
-     * <p>
-     * Cells are listed in the natural order of tensor addresses: Increasing size primarily
-     * and by element lexical order secondarily.
-     * <p>
-     * Note that while this is suggestive of JSON, it is not JSON.
+     * Returns this tensor on the
+     * <a href="https://docs.vespa.ai/documentation/reference/tensor.html#tensor-literal-form">tensor literal form</a>
+     * with type included.
      */
     @Override
     String toString();
 
     /**
-     * Call this from toString in implementations to return the standard string format.
+     * Call this from toString in implementations to return this tensor on the
+     * <a href="https://docs.vespa.ai/documentation/reference/tensor.html#tensor-literal-form">tensor literal form</a>.
      * (toString cannot be a default method because default methods cannot override super methods).
      *
      * @param tensor the tensor to return the standard string format of
@@ -345,6 +340,7 @@ public interface Tensor {
      * Returns whether this tensor and the given tensor is mathematically equal:
      * That they have the same dimension *names* and the same content.
      */
+    @Override
     boolean equals(Object o);
 
     /**
@@ -381,7 +377,8 @@ public interface Tensor {
     // ----------------- Factories
 
     /**
-     * Returns a tensor instance containing the given data on the standard string format returned by toString
+     * Returns a tensor instance containing the given data on the
+     * <a href="https://docs.vespa.ai/documentation/reference/tensor.html#tensor-literal-form">tensor literal form</a>.
      *
      * @param type the type of the tensor to return
      * @param tensorString the tensor on the standard tensor string format
@@ -391,7 +388,8 @@ public interface Tensor {
     }
 
     /**
-     * Returns a tensor instance containing the given data on the standard string format returned by toString
+     * Returns a tensor instance containing the given data on the
+     * <a href="https://docs.vespa.ai/documentation/reference/tensor.html#tensor-literal-form">tensor literal form</a>.
      *
      * @param tensorType the type of the tensor to return, as a string on the tensor type format, given in
      *        {@link TensorType#fromSpec}
@@ -402,8 +400,8 @@ public interface Tensor {
     }
 
     /**
-     * Returns a tensor instance containing the given data on the standard string format returned by toString.
-     * If a type is not specified it is derived from the first cell of the tensor
+     * Returns a tensor instance containing the given data on the
+     * <a href="https://docs.vespa.ai/documentation/reference/tensor.html#tensor-literal-form">tensor literal form</a>.
      */
     static Tensor from(String tensorString) {
         return TensorParser.tensorFrom(tensorString, Optional.empty());
diff --git a/vespajlib/src/main/java/com/yahoo/tensor/TensorType.java b/vespajlib/src/main/java/com/yahoo/tensor/TensorType.java
index d64a62143f4..bafec70be59 100644
--- a/vespajlib/src/main/java/com/yahoo/tensor/TensorType.java
+++ b/vespajlib/src/main/java/com/yahoo/tensor/TensorType.java
@@ -98,7 +98,8 @@ public class TensorType {
     }
 
     /**
-     * Returns a tensor type instance from a string on the format
+     * Returns a tensor type instance from a
+     * <a href="https://docs.vespa.ai/documentation/reference/tensor.html#tensor-type-spec">tensor type spec</a>:
      * <code>tensor(dimension1, dimension2, ...)</code>
      * where each dimension is either
      * <ul>
diff --git a/vespajlib/src/main/java/com/yahoo/tensor/serialization/JsonFormat.java b/vespajlib/src/main/java/com/yahoo/tensor/serialization/JsonFormat.java
index c73ff03a0eb..fa022e2bdd1 100644
--- a/vespajlib/src/main/java/com/yahoo/tensor/serialization/JsonFormat.java
+++ b/vespajlib/src/main/java/com/yahoo/tensor/serialization/JsonFormat.java
@@ -18,7 +18,7 @@ import java.util.Iterator;
 
 /**
  * Writes tensors on the JSON format used in Vespa tensor document fields:
- * A JSON map containing a 'cells' array.
+ * A JSON map containing a 'cells' or 'values' array.
  * See a http://docs.vespa.ai/documentation/reference/document-json-put-format.html#tensor
  *
  * @author bratseth