diff --git a/src/main/java/org/elasticsearch/index/fielddata/BytesValues.java b/src/main/java/org/elasticsearch/index/fielddata/BytesValues.java
index 9e8c49fa630..85d422d67a1 100644
--- a/src/main/java/org/elasticsearch/index/fielddata/BytesValues.java
+++ b/src/main/java/org/elasticsearch/index/fielddata/BytesValues.java
@@ -70,7 +70,12 @@ public abstract class BytesValues {
     /**
      * Returns the bytes value for the docId, with the provided "ret" which will be filled with the
      * result which will also be returned. If there is no value for this docId, the length will be 0.
-     * Note, the bytes are not "safe".
+     * Implementations can either change the {@link BytesRef#bytes bytes reference} of the {@link BytesRef}
+     * to point to an internal structure or modify the content of the {@link BytesRef} but should
+     * always do it in a consistent way. For example, it is illegal to change the bytes content in
+     * some call and to change the reference to point to an internal structure in another call, this
+     * will lead to bugs. It is also illegal for callers to write into the {@link BytesRef#bytes bytes}
+     * after this method has returned.
      */
     public abstract BytesRef getValueScratch(int docId, BytesRef ret);
 
@@ -91,10 +96,22 @@ public abstract class BytesValues {
 
     public static interface Iter {
 
+        /**
+         * Returns whether this iterator still contains elements.
+         */
         boolean hasNext();
 
+        /**
+         * Returns the next element of this iterator. Please note that the returned bytes may be
+         * reused across invocations so they should be copied for later reference. The behavior of
+         * this method is undefined if the iterator is exhausted.
+         */
         BytesRef next();
 
+        /**
+         * Returns the hash value of the last {@link BytesRef} returned by {@link #next()}. The
+         * behavior is undefined if this iterator is not positioned or exhausted.
+         */
         int hash();
 
         public static class Empty implements Iter {
@@ -266,7 +283,12 @@ public abstract class BytesValues {
         /**
          * Returns the bytes value for the docId, with the provided "ret" which will be filled with the
          * result which will also be returned. If there is no value for this docId, the length will be 0.
-         * Note, the bytes are not "safe".
+         * Implementations can either change the {@link BytesRef#bytes bytes reference} of the {@link BytesRef}
+         * to point to an internal structure or modify the content of the {@link BytesRef} but should
+         * always do it in a consistent way. For example, it is illegal to change the bytes content in
+         * some call and to change the reference to point to an internal structure in another call, this
+         * will lead to bugs. It is also illegal for callers to write into the {@link BytesRef#bytes bytes}
+         * after this method has returned.
          */
         public abstract BytesRef getValueScratchByOrd(long ord, BytesRef ret);