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.
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/util/BytesRef.java