From aec5fbe2862b6f8f82aa99c7f5eb41b0fbd32b08 Mon Sep 17 00:00:00 2001
From: leventov <leventov@ya.ru>
Date: Tue, 24 Nov 2015 16:06:02 +0300
Subject: [PATCH] Update Data javadocs

---
 .../java/net/openhft/chronicle/hash/Data.java | 63 ++++++++++++++++---
 1 file changed, 56 insertions(+), 7 deletions(-)

diff --git a/src/main/java/net/openhft/chronicle/hash/Data.java b/src/main/java/net/openhft/chronicle/hash/Data.java
index 56b031e62..78065f47d 100644
--- a/src/main/java/net/openhft/chronicle/hash/Data.java
+++ b/src/main/java/net/openhft/chronicle/hash/Data.java
@@ -39,26 +39,68 @@ import static net.openhft.chronicle.algo.bytes.Access.checkedRandomDataInputAcce
  */
 public interface Data<V> {
 
+    /**
+     * Returns the accessor object to the {@code Data}'s bytes. For safety, this interface returns
+     * read-only object, because this object could expose bytes source that must be immutable, e. g.
+     * an array behind {@code String} object.
+     */
     RandomDataInput bytes();
 
     /**
-     * Returns the offset to the value's bytes.
+     * Returns the offset to the {@code Data}'s bytes sequence, within the {@link #bytes()} object.
+     * For example, the first byte of the bytes representation of this {@code Data} instance is
+     * {@code data.bytes().readByte(data.offset())}.
      */
     long offset();
 
     /**
-     * Returns the size of the value's bytes.
+     * Returns the size of this {@code Data}'s bytes sequence. It spans from {@link #offset()} to
+     * {@code offset() + size() - 1} bytes within the {@link #bytes()} object.
      */
     long size();
 
+    /**
+     * Computes hash code on the bytes representation of this {@code Data}, using the given hash
+     * function.
+     *
+     * @param f the hash function to compute hash code using
+     * @return the hash code of this {@code Data}'s bytes, computed by the given function
+     */
     default long hash(LongHashFunction f) {
         return f.hash(bytes(), checkedRandomDataInputAccess(), offset(), size());
     }
 
+    /**
+     * Compares bytes of this {@code Data} to the given bytes {@code source}, starting from the
+     * given offset.
+     *
+     * <p>Default implementation compares {@link #bytes()} of this {@code Data}, but custom
+     * implementation may only check if {@linkplain #get() object} of this {@code Data} <i>would</i>
+     * be serialized to the same bytes sequence, if this {@code Data} is object-based and obtaining
+     * {@link #bytes()} requires serialization internally.
+     *
+     * @param source the bytes source, to compare this {@code Data}'s bytes with
+     * @param sourceOffset the offset in the bytes source, the bytes sequence starts from
+     * @return {@code true} if the given bytes sequence is equivalent to this {@code Data}'s bytes,
+     * byte-by-byte
+     */
     default boolean equivalent(RandomDataInput source, long sourceOffset) {
         return BytesUtil.bytesEqual(source, sourceOffset, bytes(), offset(), size());
     }
 
+    /**
+     * Writes bytes of this {@code Data} to the given {@code target} from the given {@code
+     * targetOffset}.
+     *
+     * <p>Default implementation copies {@link #bytes()} of this {@code Data} using standard IO
+     * methods of {@code RandomDataInput} and {@code RandomDataOutput}, but custom implementation
+     * may write directly from {@linkplain #get() object}, if this {@code Data} is object-based and
+     * obtaining {@link #bytes()} requires serialization internally. This allows to avoid double
+     * copy.
+     *
+     * @param target the destination to write this data bytes to
+     * @param targetOffset the offset in the target, to write the bytes from.
+     */
     default void writeTo(RandomDataOutput target, long targetOffset) {
         target.write(targetOffset, bytes(), offset(), size());
     }
@@ -72,15 +114,22 @@ public interface Data<V> {
     V get();
 
     /**
-     * Reads the object from the value's bytes, trying to reuse the given object
-     * (might be {@code null}).
+     * Reads the object from the value's bytes, trying to reuse the given object (might be {@code
+     * null}).
      */
     V getUsing(@Nullable V using);
 
+    /**
+     * Utility method, compares two {@code Data} instances represent equivalent bytes sequences:
+     * by comparing {@linkplain #size() their sizes}, then calling {@link
+     * #equivalent(RandomDataInput, long) d1.equivalent(d2.bytes(), d2.offset())}.
+     *
+     * @param d1 the first {@code Data} to compare
+     * @param d2 the second {@code Data} to compare
+     * @return if the given {@code Data} instances represent equivalent bytes sequences
+     */
     static boolean bytesEquivalent(Data<?> d1, Data<?> d2) {
-        if (d1.size() != d2.size())
-            return false;
-        return BytesUtil.bytesEqual(d1.bytes(), d1.offset(), d2.bytes(), d2.offset(), d1.size());
+        return d1.size() == d2.size() && d1.equivalent(d2.bytes(), d2.offset());
     }
 
     /**