Fixup javadoc and formatting in RawText and RawParseUtils

Change-Id: I9d6002941a33ec204d29e4fd920dde965387bb24
Signed-off-by: Han-Wen Nienhuys <hanwen@google.com>

2 files changed, 30 insertions, 25 deletions

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/RawText.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/RawText.java
index 27d0894899..bd41d90680 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/RawText.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/RawText.java
@@ -88,27 +88,27 @@ public class RawText extends Sequence {
 	 * The entire array (indexes 0 through length-1) is used as the content.
 	 *
 	 * @param input
-	 *            the content array. The array is never modified, so passing
-	 *            through cached arrays is safe.
+	 *            the content array. The object retains a reference to this
+	 *            array, so it should be immutable.
 	 */
-	public RawText(final byte[] input) {
+	public RawText(byte[] input) {
 		this(input, RawParseUtils.lineMap(input, 0, input.length));
 	}
 
 	/**
-	 * Create a new sequence from the existing content byte array, and the line
+	 * Create a new sequence from the existing content byte array and the line
 	 * map indicating line boundaries.
 	 *
 	 * @param input
-	 *            the content array. The array is never modified, so passing
-	 *            through cached arrays is safe.
+	 *            the content array. The object retains a reference to this
+	 *            array, so it should be immutable.
 	 * @param lineMap
-	 *            an array with the line starts of the input, in 1-based offset.
-	 *            The first and last entry should be {@link Integer#MIN_VALUE}, and the array end
-	 *            respectively.
+	 *            an array with 1-based offsets for the start of each line.
+	 *            The first and last entries should be {@link Integer#MIN_VALUE}
+	 *            and an offset one past the end of the last line, respectively.
 	 * @since 5.0
 	 */
-	public RawText(final byte[] input, IntList lineMap) {
+	public RawText(byte[] input, IntList lineMap) {
 		content = input;
 		lines = lineMap;
 	}
@@ -164,7 +164,7 @@ public class RawText extends Sequence {
 	 * @throws java.io.IOException
 	 *             the stream write operation failed.
 	 */
-	public void writeLine(final OutputStream out, final int i)
+	public void writeLine(OutputStream out, int i)
 			throws IOException {
 		int start = getStart(i);
 		int end = getEnd(i);
@@ -238,11 +238,11 @@ public class RawText extends Sequence {
 		return RawParseUtils.decode(content, start, end);
 	}
 
-	private int getStart(final int i) {
+	private int getStart(int i) {
 		return lines.get(i + 1);
 	}
 
-	private int getEnd(final int i) {
+	private int getEnd(int i) {
 		return lines.get(i + 2);
 	}
 
@@ -342,7 +342,8 @@ public class RawText extends Sequence {
 	 * @throws java.io.IOException
 	 *             if the input could not be read.
 	 */
-	public static RawText load(ObjectLoader ldr, int threshold) throws IOException, BinaryBlobException {
+	public static RawText load(ObjectLoader ldr, int threshold)
+			throws IOException, BinaryBlobException {
 		long sz = ldr.getSize();
 
 		if (sz > threshold) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java
index 490cdd3cd1..26fc9d80c5 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java
@@ -633,8 +633,9 @@ public final class RawParseUtils {
 	 *            line 1.
 	 * @param end
 	 *            1 past the end of the content within <code>buf</code>.
-	 * @return a line map indexing the start position of each line, or a map representing the entire
-	 *            array as a single line if a '\0' is found.
+	 * @return a line map indicating the starting position of each line, or a
+	 *         map representing the entire buffer as a single line if
+	 *         <code>buf</code> contains a NUL byte.
 	 */
 	public static final IntList lineMap(final byte[] buf, int ptr, int end) {
 		IntList map = lineMapOrNull(buf, ptr, end);
@@ -648,19 +649,22 @@ public final class RawParseUtils {
 	}
 
 	/**
-	 * Like {@link #lineMap(byte[], int, int)} but throw {@link BinaryBlobException} if a null char
-	 * is encountered.
-	 * @param buf  buffer to scan.
-	 * @param ptr position within the buffer corresponding to the first byte of
+	 * Like {@link #lineMap(byte[], int, int)} but throw
+	 * {@link BinaryBlobException} if a NUL byte is encountered.
+	 *
+	 * @param buf
+	 *            buffer to scan.
+	 * @param ptr
+	 *            position within the buffer corresponding to the first byte of
 	 *            line 1.
-	 * @param end  1 past the end of the content within <code>buf</code>.
-	 * @return a line map indexing the start position of each line, or a map representing the entire
-	 *            array as a single line if a '\0' is found.
+	 * @param end
+	 *            1 past the end of the content within <code>buf</code>.
+	 * @return a line map indicating the starting position of each line.
 	 * @throws BinaryBlobException
-	 *
+	 *            if a NUL byte is found.
 	 * @since 5.0
 	 */
-	public static final IntList lineMapOrBinary(final byte[] buf, int ptr, int end)
+	public static final IntList lineMapOrBinary(byte[] buf, int ptr, int end)
 			throws BinaryBlobException {
 		IntList map = lineMapOrNull(buf, ptr, end);
 		if (map == null) {