More javadoc fixes

karllessard · karllessard · commit f056482d29a9 · 2020-06-08T23:23:37.000-04:00
diff --git a/tensorflow-tools/src/main/java/org/tensorflow/tools/buffer/DataBufferWindow.java b/tensorflow-tools/src/main/java/org/tensorflow/tools/buffer/DataBufferWindow.java
@@ -1,7 +1,7 @@
 package org.tensorflow.tools.buffer;
 
 /**
- * A mutable container for view part of a {@link DataBuffer}.
+ * A mutable container for viewing part of a {@link DataBuffer}.
  *
  * <p>Data buffer windows have a fixed size and can {@link DataBufferWindow#slide(long) "slide"}
  * along a buffer to provide different views of the data without allocating a new buffer instance,
@@ -29,7 +29,7 @@
 public interface DataBufferWindow<B extends DataBuffer<?>> {
 
   /**
-   * Returns the current offset of this window in the underlying buffer.
+   * Returns the current offset of this window in the original buffer.
    */
   long offset();
 
@@ -39,36 +39,39 @@ public interface DataBufferWindow<B extends DataBuffer<?>> {
   long size();
 
   /**
-   * Moves the window at the given position in the underlying buffer.
+   * Moves the window at the given position in the original buffer.
    *
    * <p>The size of the window remains the same and its offset is set to {@code index}, so that
    * accessing the value of {@link #buffer()} at index {@code x} will return the value at
-   * {@code index + x} in the underlying buffer.
+   * {@code index + x} in the original buffer.
    *
    * @param index new offset for this window
    * @return this instance
-   * @throws IndexOutOfBoundsException if the window cannot be slid because it goes beyond buffer limits
+   * @throws IndexOutOfBoundsException if the window cannot be slid because it goes beyond
+   *                                   the original buffer limits
    */
   DataBufferWindow<B> slideTo(long index);
 
   /**
-   * Moves the window of {@code step} elements in the underlying buffer.
+   * Moves the window of {@code step} elements in the original buffer.
    *
    * <p>The size of the window remains the same and its offset is set to {@code offset() + step}.
    * If {@code step} is positive, then the window will slide forward. If it is negative, it will
    * slide backward.
    *
    * @param step value to add to the current offset of this window
    * @return this instance
-   * @throws IndexOutOfBoundsException if the window cannot be slid because it goes beyond buffer limits
+   * @throws IndexOutOfBoundsException if the window cannot be slid because it goes beyond
+   *                                   the original buffer limits
    */
   DataBufferWindow<B> slide(long step);
 
   /**
-   * Returns a buffer presenting the data currently viewed by this window.
+   * Returns the buffer backing this window.
    *
-   * <p>The same instance is always returned for a given window, even after sliding it at
-   * different offsets in the underlying buffer. For example:
+   * <p>Each window instance has it's own buffer providing a view onto the original
+   * {@link DataBuffer}. The buffers are mutated when the window slides to different offsets.
+   * For example:
    *
    * <pre>{@code
    * IntDataBuffer buffer = DataBuffers.of(0, 1, 2, 3);
