Clarify the purpose of ObjectInserter.buffer()

Recently Robin tried to increase the size of the buffer used by
ObjectInserter to fix a bug in the InputStream that handles AutoCRLF.
The purpose of this buffer is NOT to make a random InputStream work
correctly by passing it a larger buffer during read(byte[],int,int).

Clarify the Javadoc on the buffer() method to reduce the risk
someone tries to abuse it again.

While we are here, modify the method to load the field into a local
variable before returning. This should cut down 1 field load during
the common case of the buffer being already allocated.

Change-Id: Ic6898530d10fcd7e59f90397117a4a0d97e1f031
Signed-off-by: Chris Aniszczyk <zx@twitter.com>

org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java

@@ -102,11 +102,35 @@ public abstract class ObjectInserter {
 		digest = Constants.newMessageDigest();
 	}
 
-	/** @return a temporary byte array for use by the caller. */
+	/**
+	 * Obtain a temporary buffer for use by the ObjectInserter or its subclass.
+	 * <p>
+	 * This buffer is supplied by the ObjectInserter base class to itself and
+	 * its subclasses for the purposes of pulling data from a supplied
+	 * InputStream, passing it through a Deflater, or formatting the canonical
+	 * format of a small object like a small tree or commit.
+	 * <p>
+	 * <strong>This buffer IS NOT for translation such as auto-CRLF or content
+	 * filtering and must not be used for such purposes.</strong>
+	 * <p>
+	 * The returned buffer is small, around a few KiBs, and the size may change
+	 * between versions of JGit. Callers using this buffer must always check the
+	 * length of the returned array to ascertain how much space was provided.
+	 * <p>
+	 * There is a single buffer for each ObjectInserter, repeated calls to this
+	 * method will (usually) always return the same buffer. If the caller needs
+	 * more than one buffer, or needs a buffer of a larger size, it must manage
+	 * that buffer on its own.
+	 * <p>
+	 * The buffer is usually on first demand for a buffer.
+	 *
+	 * @return a temporary byte array for use by the caller.
+	 */
 	protected byte[] buffer() {
-		if (tempBuffer == null)
-			tempBuffer = new byte[8192];
-		return tempBuffer;
+		byte[] b = tempBuffer;
+		if (b == null)
+			tempBuffer = b = new byte[8192];
+		return b;
 	}
 
 	/** @return digest to help compute an ObjectId */