reftable: add some more comments

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

org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockReader.java

@@ -84,7 +84,11 @@ import org.eclipse.jgit.util.LongList;
 import org.eclipse.jgit.util.NB;
 import org.eclipse.jgit.util.RawParseUtils;
 
-/** Reads a single block for {@link ReftableReader}. */
+/**
+ * Reads a single block for {@link ReftableReader}. Instances are tied to a
+ * specific block in the file so are not reused for other blocks. Instances hold
+ * an offset into the block.
+ */
 class BlockReader {
 	private byte blockType;
 	private long endPosition;
@@ -141,6 +145,8 @@ class BlockReader {
 		return RawParseUtils.decode(UTF_8, nameBuf, 0, len);
 	}
 
+	// Matches the key against a name or a prefix. For reflogs, only the
+	// refname is matched, and the updateIndex suffix is ignored.
 	boolean match(byte[] match, boolean matchIsPrefix) {
 		int len = nameLen;
 		if (blockType == LOG_BLOCK_TYPE) {

org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java

@@ -256,8 +256,8 @@ public class ReftableReader extends Reftable {
 			return block;
 		}
 		if (blockType == LOG_BLOCK_TYPE) {
-			// No index. Log blocks are irregularly sized, so we can't do binary search
+			// No index. Log blocks are irregularly sized, so we can't do binary
-			// between blocks. Scan over blocks instead.
+			// search between blocks. Scan over blocks instead.
 			BlockReader block = readBlock(startPos, endPos);
 
 			for (;;) {
@@ -561,6 +561,14 @@ public class ReftableReader extends Reftable {
 		private ReflogEntry entry;
 		BlockReader block;
 
+		/**
+		 * Scans logs from this table until scanEnd position.
+		 *
+		 * @param scanEnd
+		 *            end of the log data in the reftable.
+		 * @param match
+		 *            if non-null, limits the scan to precisely that refname.
+		 */
 		LogCursorImpl(long scanEnd, byte[] match) {
 			this.scanEnd = scanEnd;
 			this.match = match;