Added javadocs to *Ref about clone() performing a shallow copy. I know, this is obvious and to be expected, but I fell a victim to this anyway, it's a damn thing to debug if you use clone() in hash maps etc. so perhaps it'll help somebody.

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1483681 13f79535-47bb-0310-9956-ffa450edef68

lucene/core/src/java/org/apache/lucene/util/BytesRef.java

@@ -119,11 +119,17 @@ public final class BytesRef implements Comparable<BytesRef>,Cloneable {
     }
   }
 
+  /**
+   * Returns a shallow clone of this instance (the underlying bytes are
+   * <b>not</b> copied and will be shared by both the returned object and this
+   * object.
+   * 
+   * @see #deepCopyOf
+   */
   @Override
   public BytesRef clone() {
     return new BytesRef(bytes, offset, length);
   }
-
   
   /** Calculates the hash code as required by TermsHash during indexing.
    * <p>It is defined as:

lucene/core/src/java/org/apache/lucene/util/CharsRef.java

@@ -71,6 +71,13 @@ public final class CharsRef implements Comparable<CharsRef>, CharSequence, Clone
     this.length = chars.length;
   }
 
+  /**
+   * Returns a shallow clone of this instance (the underlying characters are
+   * <b>not</b> copied and will be shared by both the returned object and this
+   * object.
+   * 
+   * @see #deepCopyOf
+   */  
   @Override
   public CharsRef clone() {
     return new CharsRef(chars, offset, length);

lucene/core/src/java/org/apache/lucene/util/IntsRef.java

@@ -56,6 +56,13 @@ public final class IntsRef implements Comparable<IntsRef>, Cloneable {
     assert isValid();
   }
 
+  /**
+   * Returns a shallow clone of this instance (the underlying ints are
+   * <b>not</b> copied and will be shared by both the returned object and this
+   * object.
+   * 
+   * @see #deepCopyOf
+   */  
   @Override
   public IntsRef clone() {
     return new IntsRef(ints, offset, length);

lucene/core/src/java/org/apache/lucene/util/LongsRef.java

@@ -55,6 +55,13 @@ public final class LongsRef implements Comparable<LongsRef>, Cloneable {
     assert isValid();
   }
 
+  /**
+   * Returns a shallow clone of this instance (the underlying longs are
+   * <b>not</b> copied and will be shared by both the returned object and this
+   * object.
+   * 
+   * @see #deepCopyOf
+   */  
   @Override
   public LongsRef clone() {
     return new LongsRef(longs, offset, length);