Fix javadoc in org.eclipse.jgit storage/reftable package

Change-Id: I14764c5d5b2309d82fe2ccc0593120b51328bf41
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>

11 files changed, 215 insertions, 57 deletions

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockSizeTooSmallException.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockSizeTooSmallException.java
index cb0f988b23..991306e0a6 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockSizeTooSmallException.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockSizeTooSmallException.java
@@ -45,7 +45,10 @@ package org.eclipse.jgit.internal.storage.reftable;
 
 import java.io.IOException;
 
-/** Thrown if {@link ReftableWriter} cannot fit a reference. */
+/**
+ * Thrown if {@link org.eclipse.jgit.internal.storage.reftable.ReftableWriter}
+ * cannot fit a reference.
+ */
 public class BlockSizeTooSmallException extends IOException {
 	private static final long serialVersionUID = 1L;
 
@@ -55,7 +58,11 @@ public class BlockSizeTooSmallException extends IOException {
 		minBlockSize = b;
 	}
 
-	/** @return minimum block size in bytes reftable requires to write a ref. */
+	/**
+	 * Get minimum block size in bytes reftable requires to write a ref.
+	 *
+	 * @return minimum block size in bytes reftable requires to write a ref.
+	 */
 	public int getMinimumBlockSize() {
 		return minBlockSize;
 	}
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/EmptyLogCursor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/EmptyLogCursor.java
index d7745891a5..de5baa1c18 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/EmptyLogCursor.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/EmptyLogCursor.java
@@ -49,26 +49,31 @@ import org.eclipse.jgit.lib.ReflogEntry;
 
 /** Empty {@link LogCursor} with no results. */
 class EmptyLogCursor extends LogCursor {
+	/** {@inheritDoc} */
 	@Override
 	public boolean next() throws IOException {
 		return false;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public String getRefName() {
 		return null;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public long getUpdateIndex() {
 		return 0;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public ReflogEntry getReflogEntry() {
 		return null;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void close() {
 		// Do nothing.
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/LogCursor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/LogCursor.java
index c19968c098..486fd28984 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/LogCursor.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/LogCursor.java
@@ -47,26 +47,42 @@ import java.io.IOException;
 
 import org.eclipse.jgit.lib.ReflogEntry;
 
-/** Iterator over logs inside a {@link Reftable}. */
+/**
+ * Iterator over logs inside a
+ * {@link org.eclipse.jgit.internal.storage.reftable.Reftable}.
+ */
 public abstract class LogCursor implements AutoCloseable {
 	/**
 	 * Check if another log record is available.
 	 *
 	 * @return {@code true} if there is another result.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             logs cannot be read.
 	 */
 	public abstract boolean next() throws IOException;
 
-	/** @return name of the current reference. */
+	/**
+	 * Get name of the current reference.
+	 *
+	 * @return name of the current reference.
+	 */
 	public abstract String getRefName();
 
-	/** @return identifier of the transaction that created the log record. */
+	/**
+	 * Get identifier of the transaction that created the log record.
+	 *
+	 * @return identifier of the transaction that created the log record.
+	 */
 	public abstract long getUpdateIndex();
 
-	/** @return current log entry. */
+	/**
+	 * Get current log entry.
+	 *
+	 * @return current log entry.
+	 */
 	public abstract ReflogEntry getReflogEntry();
 
+	/** {@inheritDoc} */
 	@Override
 	public abstract void close();
 }
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/MergedReftable.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/MergedReftable.java
index 9fc6ae2bb4..baebde2b48 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/MergedReftable.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/MergedReftable.java
@@ -54,8 +54,10 @@ import org.eclipse.jgit.lib.ReflogEntry;
 /**
  * Merges multiple reference tables together.
  * <p>
- * A {@link MergedReftable} merge-joins multiple {@link ReftableReader} on the
- * fly. Tables higher/later in the stack shadow lower/earlier tables, hiding
+ * A {@link org.eclipse.jgit.internal.storage.reftable.MergedReftable}
+ * merge-joins multiple
+ * {@link org.eclipse.jgit.internal.storage.reftable.ReftableReader} on the fly.
+ * Tables higher/later in the stack shadow lower/earlier tables, hiding
  * references that been updated/replaced.
  * <p>
  * By default deleted references are skipped and not returned to the caller.
@@ -89,6 +91,7 @@ public class MergedReftable extends Reftable {
 		}
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public RefCursor allRefs() throws IOException {
 		MergedRefCursor m = new MergedRefCursor();
@@ -98,6 +101,7 @@ public class MergedReftable extends Reftable {
 		return m;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public RefCursor seekRef(String name) throws IOException {
 		MergedRefCursor m = new MergedRefCursor();
@@ -107,6 +111,7 @@ public class MergedReftable extends Reftable {
 		return m;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public RefCursor byObjectId(AnyObjectId name) throws IOException {
 		MergedRefCursor m = new MergedRefCursor();
@@ -116,6 +121,7 @@ public class MergedReftable extends Reftable {
 		return m;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public LogCursor allLogs() throws IOException {
 		MergedLogCursor m = new MergedLogCursor();
@@ -125,6 +131,7 @@ public class MergedReftable extends Reftable {
 		return m;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public LogCursor seekLog(String refName, long updateIdx)
 			throws IOException {
@@ -135,6 +142,7 @@ public class MergedReftable extends Reftable {
 		return m;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void close() throws IOException {
 		for (Reftable t : tables) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/RefCursor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/RefCursor.java
index d8e9c609f0..5d4af30a91 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/RefCursor.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/RefCursor.java
@@ -47,29 +47,45 @@ import java.io.IOException;
 
 import org.eclipse.jgit.lib.Ref;
 
-/** Iterator over references inside a {@link Reftable}. */
+/**
+ * Iterator over references inside a
+ * {@link org.eclipse.jgit.internal.storage.reftable.Reftable}.
+ */
 public abstract class RefCursor implements AutoCloseable {
 	/**
 	 * Check if another reference is available.
 	 *
 	 * @return {@code true} if there is another result.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             references cannot be read.
 	 */
 	public abstract boolean next() throws IOException;
 
-	/** @return reference at the current position. */
+	/**
+	 * Get reference at the current position.
+	 *
+	 * @return reference at the current position.
+	 */
 	public abstract Ref getRef();
 
-	/** @return updateIndex that last modified the current reference, */
+	/**
+	 * Get updateIndex that last modified the current reference.
+	 *
+	 * @return updateIndex that last modified the current reference.
+	 */
 	public abstract long getUpdateIndex();
 
-	/** @return {@code true} if the current reference was deleted. */
+	/**
+	 * Whether the current reference was deleted.
+	 *
+	 * @return {@code true} if the current reference was deleted.
+	 */
 	public boolean wasDeleted() {
 		Ref r = getRef();
 		return r.getStorage() == Ref.Storage.NEW && r.getObjectId() == null;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public abstract void close();
 }
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/Reftable.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/Reftable.java
index 1189ed3b96..510c1a14e0 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/Reftable.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/Reftable.java
@@ -55,9 +55,13 @@ import org.eclipse.jgit.lib.AnyObjectId;
 import org.eclipse.jgit.lib.Ref;
 import org.eclipse.jgit.lib.SymbolicRef;
 
-/** Abstract table of references. */
+/**
+ * Abstract table of references.
+ */
 public abstract class Reftable implements AutoCloseable {
 	/**
+	 * References to convert into a reftable
+	 *
 	 * @param refs
 	 *            references to convert into a reftable; may be empty.
 	 * @return a reader for the supplied references.
@@ -83,6 +87,8 @@ public abstract class Reftable implements AutoCloseable {
 	protected boolean includeDeletes;
 
 	/**
+	 * Whether deleted references will be returned.
+	 *
 	 * @param deletes
 	 *            if {@code true} deleted references will be returned. If
 	 *            {@code false} (default behavior), deleted references will be
@@ -96,7 +102,7 @@ public abstract class Reftable implements AutoCloseable {
 	 * Seek to the first reference, to iterate in order.
 	 *
 	 * @return cursor to iterate.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if references cannot be read.
 	 */
 	public abstract RefCursor allRefs() throws IOException;
@@ -115,7 +121,7 @@ public abstract class Reftable implements AutoCloseable {
 	 * @param refName
 	 *            reference name or subtree to find.
 	 * @return cursor to iterate; empty cursor if no references match.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if references cannot be read.
 	 */
 	public abstract RefCursor seekRef(String refName) throws IOException;
@@ -126,7 +132,7 @@ public abstract class Reftable implements AutoCloseable {
 	 * @param id
 	 *            object to find.
 	 * @return cursor to iterate; empty cursor if no references match.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if references cannot be read.
 	 */
 	public abstract RefCursor byObjectId(AnyObjectId id) throws IOException;
@@ -135,7 +141,7 @@ public abstract class Reftable implements AutoCloseable {
 	 * Seek reader to read log records.
 	 *
 	 * @return cursor to iterate; empty cursor if no logs are present.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if logs cannot be read.
 	 */
 	public abstract LogCursor allLogs() throws IOException;
@@ -146,7 +152,7 @@ public abstract class Reftable implements AutoCloseable {
 	 * @param refName
 	 *            exact name of the reference whose log to read.
 	 * @return cursor to iterate; empty cursor if no logs match.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if logs cannot be read.
 	 */
 	public LogCursor seekLog(String refName) throws IOException {
@@ -162,7 +168,7 @@ public abstract class Reftable implements AutoCloseable {
 	 *            most recent index to return first in the log cursor. Log
 	 *            records at or before {@code updateIndex} will be returned.
 	 * @return cursor to iterate; empty cursor if no logs match.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if logs cannot be read.
 	 */
 	public abstract LogCursor seekLog(String refName, long updateIndex)
@@ -174,7 +180,7 @@ public abstract class Reftable implements AutoCloseable {
 	 * @param refName
 	 *            reference name to find.
 	 * @return the reference, or {@code null} if not found.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if references cannot be read.
 	 */
 	@Nullable
@@ -196,7 +202,7 @@ public abstract class Reftable implements AutoCloseable {
 	 *            reference name or subtree to find.
 	 * @return {@code true} if the reference exists, or at least one reference
 	 *         exists in the subtree.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if references cannot be read.
 	 */
 	public boolean hasRef(String refName) throws IOException {
@@ -212,7 +218,7 @@ public abstract class Reftable implements AutoCloseable {
 	 *            ObjectId to find.
 	 * @return {@code true} if any reference exists directly referencing
 	 *         {@code id}, or a annotated tag that peels to {@code id}.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if references cannot be read.
 	 */
 	public boolean hasId(AnyObjectId id) throws IOException {
@@ -227,7 +233,7 @@ public abstract class Reftable implements AutoCloseable {
 	 * @param symref
 	 *            reference to resolve.
 	 * @return resolved {@code symref}, or {@code null}.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if references cannot be read.
 	 */
 	@Nullable
@@ -257,6 +263,7 @@ public abstract class Reftable implements AutoCloseable {
 		return new SymbolicRef(ref.getName(), dst);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public abstract void close() throws IOException;
 }
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableCompactor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableCompactor.java
index 6b53d41763..ed73a9efbd 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableCompactor.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableCompactor.java
@@ -80,6 +80,8 @@ public class ReftableCompactor {
 	private Stats stats;
 
 	/**
+	 * Set configuration for the reftable.
+	 *
 	 * @param cfg
 	 *            configuration for the reftable.
 	 * @return {@code this}
@@ -90,6 +92,8 @@ public class ReftableCompactor {
 	}
 
 	/**
+	 * Set limit on number of bytes from source tables to compact.
+	 *
 	 * @param bytes
 	 *            limit on number of bytes from source tables to compact.
 	 * @return {@code this}
@@ -100,6 +104,9 @@ public class ReftableCompactor {
 	}
 
 	/**
+	 * Whether to include deletions in the output, which may be necessary for
+	 * partial compaction.
+	 *
 	 * @param deletes
 	 *            {@code true} to include deletions in the output, which may be
 	 *            necessary for partial compaction.
@@ -111,6 +118,9 @@ public class ReftableCompactor {
 	}
 
 	/**
+	 * Set the minimum update index for log entries that appear in the compacted
+	 * reftable.
+	 *
 	 * @param min
 	 *            the minimum update index for log entries that appear in the
 	 *            compacted reftable. This should be 1 higher than the prior
@@ -124,6 +134,9 @@ public class ReftableCompactor {
 	}
 
 	/**
+	 * Set the maximum update index for log entries that appear in the compacted
+	 * reftable.
+	 *
 	 * @param max
 	 *            the maximum update index for log entries that appear in the
 	 *            compacted reftable. This should be at least 1 higher than the
@@ -137,6 +150,8 @@ public class ReftableCompactor {
 	}
 
 	/**
+	 * Set oldest reflog time to preserve.
+	 *
 	 * @param timeMillis
 	 *            oldest log time to preserve. Entries whose timestamps are
 	 *            {@code >= timeMillis} will be copied into the output file. Log
@@ -159,7 +174,7 @@ public class ReftableCompactor {
 	 *            tables to compact. Tables should be ordered oldest first/most
 	 *            recent last so that the more recent tables can shadow the
 	 *            older results. Caller is responsible for closing the readers.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             update indexes of a reader cannot be accessed.
 	 */
 	public void addAll(List<? extends Reftable> readers) throws IOException {
@@ -184,7 +199,7 @@ public class ReftableCompactor {
 	 *            responsible for closing the reader.
 	 * @return {@code true} if the compactor accepted this table; {@code false}
 	 *         if the compactor has reached its limit.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if size of {@code reader}, or its update indexes cannot be read.
 	 */
 	public boolean tryAddFirst(ReftableReader reader) throws IOException {
@@ -213,7 +228,7 @@ public class ReftableCompactor {
 	 * @param out
 	 *            stream to write the compacted tables to. Caller is responsible
 	 *            for closing {@code out}.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if tables cannot be read, or cannot be written.
 	 */
 	public void compact(OutputStream out) throws IOException {
@@ -229,7 +244,11 @@ public class ReftableCompactor {
 		stats = writer.getStats();
 	}
 
-	/** @return statistics of the last written reftable. */
+	/**
+	 * Get statistics of the last written reftable.
+	 *
+	 * @return statistics of the last written reftable.
+	 */
 	public Stats getStats() {
 		return stats;
 	}
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableConfig.java
index f7a1fbe2af..66c113d1ec 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableConfig.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableConfig.java
@@ -48,7 +48,9 @@ import static org.eclipse.jgit.internal.storage.reftable.ReftableConstants.MAX_B
 import org.eclipse.jgit.lib.Config;
 import org.eclipse.jgit.lib.Repository;
 
-/** Configuration used by a reftable writer when constructing the stream. */
+/**
+ * Configuration used by a reftable writer when constructing the stream.
+ */
 public class ReftableConfig {
 	private int refBlockSize = 4 << 10;
 	private int logBlockSize;
@@ -57,7 +59,9 @@ public class ReftableConfig {
 	private boolean alignBlocks = true;
 	private boolean indexObjects = true;
 
-	/** Create a default configuration. */
+	/**
+	 * Create a default configuration.
+	 */
 	public ReftableConfig() {
 	}
 
@@ -74,7 +78,8 @@ public class ReftableConfig {
 	}
 
 	/**
-	 * Create a configuration honoring settings in a {@link Config}.
+	 * Create a configuration honoring settings in a
+	 * {@link org.eclipse.jgit.lib.Config}.
 	 *
 	 * @param cfg
 	 *            the source to read settings from. The source is not retained
@@ -100,12 +105,18 @@ public class ReftableConfig {
 		this.indexObjects = cfg.indexObjects;
 	}
 
-	/** @return desired output block size for references, in bytes */
+	/**
+	 * Get desired output block size for references, in bytes.
+	 *
+	 * @return desired output block size for references, in bytes.
+	 */
 	public int getRefBlockSize() {
 		return refBlockSize;
 	}
 
 	/**
+	 * Set desired output block size for references, in bytes.
+	 *
 	 * @param szBytes
 	 *            desired output block size for references, in bytes.
 	 */
@@ -117,6 +128,8 @@ public class ReftableConfig {
 	}
 
 	/**
+	 * Get desired output block size for log entries, in bytes.
+	 *
 	 * @return desired output block size for log entries, in bytes. If 0 the
 	 *         writer will default to {@code 2 * getRefBlockSize()}.
 	 */
@@ -125,6 +138,8 @@ public class ReftableConfig {
 	}
 
 	/**
+	 * Set desired output block size for log entries, in bytes.
+	 *
 	 * @param szBytes
 	 *            desired output block size for log entries, in bytes. If 0 will
 	 *            default to {@code 2 * getRefBlockSize()}.
@@ -136,12 +151,18 @@ public class ReftableConfig {
 		logBlockSize = Math.max(0, szBytes);
 	}
 
-	/** @return number of references between binary search markers. */
+	/**
+	 * Get number of references between binary search markers.
+	 *
+	 * @return number of references between binary search markers.
+	 */
 	public int getRestartInterval() {
 		return restartInterval;
 	}
 
 	/**
+	 * <p>Setter for the field <code>restartInterval</code>.</p>
+	 *
 	 * @param interval
 	 *            number of references between binary search markers. If
 	 *            {@code interval} is 0 (default), the writer will select a
@@ -151,12 +172,18 @@ public class ReftableConfig {
 		restartInterval = Math.max(0, interval);
 	}
 
-	/** @return maximum depth of the index; 0 for unlimited. */
+	/**
+	 * Get maximum depth of the index; 0 for unlimited.
+	 *
+	 * @return maximum depth of the index; 0 for unlimited.
+	 */
 	public int getMaxIndexLevels() {
 		return maxIndexLevels;
 	}
 
 	/**
+	 * Set maximum number of levels to use in indexes.
+	 *
 	 * @param levels
 	 *            maximum number of levels to use in indexes. Lower levels of
 	 *            the index respect {@link #getRefBlockSize()}, and the highest
@@ -166,12 +193,19 @@ public class ReftableConfig {
 		maxIndexLevels = Math.max(0, levels);
 	}
 
-	/** @return {@code true} if the writer should align blocks. */
+	/**
+	 * Whether the writer should align blocks.
+	 *
+	 * @return {@code true} if the writer should align blocks.
+	 */
 	public boolean isAlignBlocks() {
 		return alignBlocks;
 	}
 
 	/**
+	 * Whether blocks are written aligned to multiples of
+	 * {@link #getRefBlockSize()}.
+	 *
 	 * @param align
 	 *            if {@code true} blocks are written aligned to multiples of
 	 *            {@link #getRefBlockSize()}. May increase file size due to NUL
@@ -181,12 +215,19 @@ public class ReftableConfig {
 		alignBlocks = align;
 	}
 
-	/** @return {@code true} if the writer should index object to ref. */
+	/**
+	 * Whether the writer should index object to ref.
+	 *
+	 * @return {@code true} if the writer should index object to ref.
+	 */
 	public boolean isIndexObjects() {
 		return indexObjects;
 	}
 
 	/**
+	 * Whether the reftable may include additional storage to efficiently map
+	 * from {@code ObjectId} to reference names.
+	 *
 	 * @param index
 	 *            if {@code true} the reftable may include additional storage to
 	 *            efficiently map from {@code ObjectId} to reference names. By
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableOutputStream.java
index a24619b2c5..1fc43c9fac 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableOutputStream.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableOutputStream.java
@@ -92,12 +92,14 @@ class ReftableOutputStream extends OutputStream {
 		blockSize = bs;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void write(int b) {
 		ensureBytesAvailableInBlockBuf(1);
 		blockBuf[cur++] = (byte) b;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void write(byte[] b, int off, int cnt) {
 		ensureBytesAvailableInBlockBuf(cnt);
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java
index 407a77c7d3..74877192f6 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java
@@ -112,10 +112,13 @@ public class ReftableReader extends Reftable {
 	}
 
 	/**
+	 * Get the block size in bytes chosen for this file by the writer.
+	 *
 	 * @return the block size in bytes chosen for this file by the writer. Most
-	 *         reads from the {@link BlockSource} will be aligned to the block
-	 *         size.
-	 * @throws IOException
+	 *         reads from the
+	 *         {@link org.eclipse.jgit.internal.storage.io.BlockSource} will be
+	 *         aligned to the block size.
+	 * @throws java.io.IOException
 	 *             file cannot be read.
 	 */
 	public int blockSize() throws IOException {
@@ -126,10 +129,13 @@ public class ReftableReader extends Reftable {
 	}
 
 	/**
+	 * Get the minimum update index for log entries that appear in this
+	 * reftable.
+	 *
 	 * @return the minimum update index for log entries that appear in this
 	 *         reftable. This should be 1 higher than the prior reftable's
 	 *         {@code maxUpdateIndex} if this table is used in a stack.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             file cannot be read.
 	 */
 	public long minUpdateIndex() throws IOException {
@@ -140,10 +146,13 @@ public class ReftableReader extends Reftable {
 	}
 
 	/**
+	 * Get the maximum update index for log entries that appear in this
+	 * reftable.
+	 *
 	 * @return the maximum update index for log entries that appear in this
 	 *         reftable. This should be 1 higher than the prior reftable's
 	 *         {@code maxUpdateIndex} if this table is used in a stack.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             file cannot be read.
 	 */
 	public long maxUpdateIndex() throws IOException {
@@ -153,6 +162,7 @@ public class ReftableReader extends Reftable {
 		return maxUpdateIndex;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public RefCursor allRefs() throws IOException {
 		if (blockSize == -1) {
@@ -167,6 +177,7 @@ public class ReftableReader extends Reftable {
 		return i;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public RefCursor seekRef(String refName) throws IOException {
 		initRefIndex();
@@ -179,6 +190,7 @@ public class ReftableReader extends Reftable {
 		return i;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public RefCursor byObjectId(AnyObjectId id) throws IOException {
 		initObjIndex();
@@ -191,6 +203,7 @@ public class ReftableReader extends Reftable {
 		return i;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public LogCursor allLogs() throws IOException {
 		initLogIndex();
@@ -203,6 +216,7 @@ public class ReftableReader extends Reftable {
 		return new EmptyLogCursor();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public LogCursor seekLog(String refName, long updateIndex)
 			throws IOException {
@@ -437,13 +451,14 @@ public class ReftableReader extends Reftable {
 	 * Get size of the reftable, in bytes.
 	 *
 	 * @return size of the reftable, in bytes.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             size cannot be obtained.
 	 */
 	public long size() throws IOException {
 		return src.size();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void close() throws IOException {
 		src.close();
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableWriter.java
index 0ac2445fc0..f8b9ffd176 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableWriter.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableWriter.java
@@ -89,7 +89,9 @@ import org.eclipse.jgit.util.NB;
  * Writes a reftable formatted file.
  * <p>
  * A reftable can be written in a streaming fashion, provided the caller sorts
- * all references. A {@link ReftableWriter} is single-use, and not thread-safe.
+ * all references. A
+ * {@link org.eclipse.jgit.internal.storage.reftable.ReftableWriter} is
+ * single-use, and not thread-safe.
  */
 public class ReftableWriter {
 	private ReftableConfig config;
@@ -113,7 +115,9 @@ public class ReftableWriter {
 	private int objIdLen;
 	private Stats stats;
 
-	/** Initialize a writer with a default configuration. */
+	/**
+	 * Initialize a writer with a default configuration.
+	 */
 	public ReftableWriter() {
 		this(new ReftableConfig());
 	}
@@ -129,6 +133,8 @@ public class ReftableWriter {
 	}
 
 	/**
+	 * Set configuration for the writer.
+	 *
 	 * @param cfg
 	 *            configuration for the writer.
 	 * @return {@code this}
@@ -139,6 +145,9 @@ public class ReftableWriter {
 	}
 
 	/**
+	 * Set the minimum update index for log entries that appear in this
+	 * reftable.
+	 *
 	 * @param min
 	 *            the minimum update index for log entries that appear in this
 	 *            reftable. This should be 1 higher than the prior reftable's
@@ -151,6 +160,9 @@ public class ReftableWriter {
 	}
 
 	/**
+	 * Set the maximum update index for log entries that appear in this
+	 * reftable.
+	 *
 	 * @param max
 	 *            the maximum update index for log entries that appear in this
 	 *            reftable. This should be at least 1 higher than the prior
@@ -170,7 +182,7 @@ public class ReftableWriter {
 	 *            stream to write the table to. Caller is responsible for
 	 *            closing the stream after invoking {@link #finish()}.
 	 * @return {@code this}
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if reftable header cannot be written.
 	 */
 	public ReftableWriter begin(OutputStream os) throws IOException {
@@ -208,7 +220,7 @@ public class ReftableWriter {
 	 * @param refsToPack
 	 *            references to sort and write.
 	 * @return {@code this}
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if reftable cannot be written.
 	 */
 	public ReftableWriter sortAndWriteRefs(Collection<Ref> refsToPack)
@@ -232,7 +244,7 @@ public class ReftableWriter {
 	 *
 	 * @param ref
 	 *            the reference to store.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if reftable cannot be written.
 	 */
 	public void writeRef(Ref ref) throws IOException {
@@ -249,7 +261,7 @@ public class ReftableWriter {
 	 * @param updateIndex
 	 *            the updateIndex that modified this reference. Must be
 	 *            {@code >= minUpdateIndex} for this file.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if reftable cannot be written.
 	 */
 	public void writeRef(Ref ref, long updateIndex) throws IOException {
@@ -295,12 +307,14 @@ public class ReftableWriter {
 	 * @param who
 	 *            committer of the reflog entry.
 	 * @param oldId
-	 *            prior id; pass {@link ObjectId#zeroId()} for creations.
+	 *            prior id; pass {@link org.eclipse.jgit.lib.ObjectId#zeroId()}
+	 *            for creations.
 	 * @param newId
-	 *            new id; pass {@link ObjectId#zeroId()} for deletions.
+	 *            new id; pass {@link org.eclipse.jgit.lib.ObjectId#zeroId()}
+	 *            for deletions.
 	 * @param message
 	 *            optional message (may be null).
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if reftable cannot be written.
 	 */
 	public void writeLog(String ref, long updateIndex, PersonIdent who,
@@ -327,7 +341,7 @@ public class ReftableWriter {
 	 *            the ref to delete (hide) a reflog entry from.
 	 * @param updateIndex
 	 *            the update index that must be hidden.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if reftable cannot be written.
 	 */
 	public void deleteLog(String ref, long updateIndex) throws IOException {
@@ -345,10 +359,14 @@ public class ReftableWriter {
 	}
 
 	/**
+	 * Get an estimate of the current size in bytes of the reftable
+	 *
 	 * @return an estimate of the current size in bytes of the reftable, if it
 	 *         was finished right now. Estimate is only accurate if
-	 *         {@link ReftableConfig#setIndexObjects(boolean)} is {@code false}
-	 *         and {@link ReftableConfig#setMaxIndexLevels(int)} is {@code 1}.
+	 *         {@link org.eclipse.jgit.internal.storage.reftable.ReftableConfig#setIndexObjects(boolean)}
+	 *         is {@code false} and
+	 *         {@link org.eclipse.jgit.internal.storage.reftable.ReftableConfig#setMaxIndexLevels(int)}
+	 *         is {@code 1}.
 	 */
 	public long estimateTotalBytes() {
 		long bytes = out.size();
@@ -381,7 +399,7 @@ public class ReftableWriter {
 	 * Finish writing the reftable by writing its trailer.
 	 *
 	 * @return {@code this}
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if reftable cannot be written.
 	 */
 	public ReftableWriter finish() throws IOException {
@@ -480,7 +498,11 @@ public class ReftableWriter {
 		return s != null && s.idx != null ? s.idx.rootPosition : 0;
 	}
 
-	/** @return statistics of the last written reftable. */
+	/**
+	 * Get statistics of the last written reftable.
+	 *
+	 * @return statistics of the last written reftable.
+	 */
 	public Stats getStats() {
 		return stats;
 	}