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

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

org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/CachedPack.java

@@ -45,13 +45,17 @@ package org.eclipse.jgit.internal.storage.pack;
 
 import java.io.IOException;
 
-/** Describes a pack file {@link ObjectReuseAsIs} can append onto a stream. */
+/**
+ * Describes a pack file
+ * {@link org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs} can append
+ * onto a stream.
+ */
 public abstract class CachedPack {
 	/**
 	 * Get the number of objects in this pack.
 	 *
 	 * @return the total object count for the pack.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if the object count cannot be read.
 	 */
 	public abstract long getObjectCount() throws IOException;
@@ -70,7 +74,7 @@ public abstract class CachedPack {
 	 *
 	 * @return the number of deltas; 0 if the number is not known or there are
 	 *         no deltas.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if the delta count cannot be read.
 	 */
 	public long getDeltaCount() throws IOException {
@@ -88,15 +92,16 @@ public abstract class CachedPack {
 	 * only and using its internal state to decide if this object is within this
 	 * pack. Implementors should ensure a representation from this cached pack
 	 * is tested as part of
-	 * {@link ObjectReuseAsIs#selectObjectRepresentation(PackWriter, org.eclipse.jgit.lib.ProgressMonitor, Iterable)}
+	 * {@link org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs#selectObjectRepresentation(PackWriter, org.eclipse.jgit.lib.ProgressMonitor, Iterable)}
 	 * , ensuring this method would eventually return true if the object would
 	 * be included by this cached pack.
 	 *
 	 * @param obj
 	 *            the object being packed. Can be used as an ObjectId.
 	 * @param rep
-	 *            representation from the {@link ObjectReuseAsIs} instance that
-	 *            originally supplied this CachedPack.
+	 *            representation from the
+	 *            {@link org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs}
+	 *            instance that originally supplied this CachedPack.
 	 * @return true if this pack contains this object.
 	 */
 	public abstract boolean hasObject(ObjectToPack obj,

org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaEncoder.java

@@ -48,7 +48,10 @@ import java.io.OutputStream;
 
 import org.eclipse.jgit.lib.Constants;
 
-/** Encodes an instruction stream for {@link BinaryDelta}. */
+/**
+ * Encodes an instruction stream for
+ * {@link org.eclipse.jgit.internal.storage.pack.BinaryDelta}.
+ */
 public class DeltaEncoder {
 	/**
 	 * Maximum number of bytes to be copied in pack v2 format.
@@ -91,7 +94,7 @@ public class DeltaEncoder {
 	 * @param resultSize
 	 *            size of the resulting object, after applying this instruction
 	 *            stream to the base object, in bytes.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the output buffer cannot store the instruction stream's
 	 *             header with the size fields.
 	 */
@@ -114,7 +117,7 @@ public class DeltaEncoder {
 	 *            maximum number of bytes to write to the out buffer declaring
 	 *            the stream is over limit and should be discarded. May be 0 to
 	 *            specify an infinite limit.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the output buffer cannot store the instruction stream's
 	 *             header with the size fields.
 	 */
@@ -138,7 +141,11 @@ public class DeltaEncoder {
 			out.write(buf, 0, p);
 	}
 
-	/** @return current size of the delta stream, in bytes. */
+	/**
+	 * Get current size of the delta stream, in bytes.
+	 *
+	 * @return current size of the delta stream, in bytes.
+	 */
 	public int getSize() {
 		return size;
 	}
@@ -150,7 +157,7 @@ public class DeltaEncoder {
 	 *            the string to insert.
 	 * @return true if the insert fits within the limit; false if the insert
 	 *         would cause the instruction stream to exceed the limit.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the instruction buffer can't store the instructions.
 	 */
 	public boolean insert(String text) throws IOException {
@@ -164,7 +171,7 @@ public class DeltaEncoder {
 	 *            the binary to insert.
 	 * @return true if the insert fits within the limit; false if the insert
 	 *         would cause the instruction stream to exceed the limit.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the instruction buffer can't store the instructions.
 	 */
 	public boolean insert(byte[] text) throws IOException {
@@ -182,7 +189,7 @@ public class DeltaEncoder {
 	 *            number of bytes to insert.
 	 * @return true if the insert fits within the limit; false if the insert
 	 *         would cause the instruction stream to exceed the limit.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the instruction buffer can't store the instructions.
 	 */
 	public boolean insert(byte[] text, int off, int cnt)
@@ -217,7 +224,7 @@ public class DeltaEncoder {
 	 *            number of bytes to copy.
 	 * @return true if the copy fits within the limit; false if the copy
 	 *         would cause the instruction stream to exceed the limit.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the instruction buffer cannot store the instructions.
 	 */
 	public boolean copy(long offset, int cnt) throws IOException {

org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaIndex.java

@@ -51,8 +51,9 @@ import java.io.OutputStream;
  * <p>
  * The index can be passed a result buffer, and output an instruction sequence
  * that transforms the source buffer used by the index into the result buffer.
- * The instruction sequence can be executed by {@link BinaryDelta} to recreate
- * the result buffer.
+ * The instruction sequence can be executed by
+ * {@link org.eclipse.jgit.internal.storage.pack.BinaryDelta} to recreate the
+ * result buffer.
  * <p>
  * An index stores the entire contents of the source buffer, but also a table of
  * block identities mapped to locations where the block appears in the source
@@ -191,7 +192,11 @@ public class DeltaIndex {
 		}
 	}
 
-	/** @return size of the source buffer this index has scanned. */
+	/**
+	 * Get size of the source buffer this index has scanned.
+	 *
+	 * @return size of the source buffer this index has scanned.
+	 */
 	public long getSourceSize() {
 		return src.length;
 	}
@@ -244,7 +249,7 @@ public class DeltaIndex {
 	 *            the desired result buffer. The generated instructions will
 	 *            recreate this buffer when applied to the source buffer stored
 	 *            within this index.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the output stream refused to write the instructions.
 	 */
 	public void encode(OutputStream out, byte[] res) throws IOException {
@@ -274,7 +279,7 @@ public class DeltaIndex {
 	 * @return true if the delta is smaller than deltaSizeLimit; false if the
 	 *         encoder aborted because the encoded delta instructions would be
 	 *         longer than deltaSizeLimit bytes.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the output stream refused to write the instructions.
 	 */
 	public boolean encode(OutputStream out, byte[] res, int deltaSizeLimit)
@@ -421,6 +426,7 @@ public class DeltaIndex {
 		return start - resPtr;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	@SuppressWarnings("nls")
 	public String toString() {

org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaTask.java

@@ -292,6 +292,7 @@ final class DeltaTask implements Callable<Object> {
 		slices.add(s);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public Object call() throws Exception {
 		or = block.templateReader.newReader();

org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectReuseAsIs.java

@@ -51,26 +51,27 @@ import org.eclipse.jgit.errors.MissingObjectException;
 import org.eclipse.jgit.errors.StoredObjectRepresentationNotAvailableException;
 import org.eclipse.jgit.lib.AnyObjectId;
 import org.eclipse.jgit.lib.BitmapIndex.BitmapBuilder;
-import org.eclipse.jgit.lib.ObjectReader;
 import org.eclipse.jgit.lib.ProgressMonitor;
 
 /**
- * Extension of {@link ObjectReader} that supports reusing objects in packs.
+ * Extension of {@link org.eclipse.jgit.lib.ObjectReader} that supports reusing
+ * objects in packs.
  * <p>
  * {@code ObjectReader} implementations may also optionally implement this
- * interface to support {@link PackWriter} with a means of copying an object
- * that is already in pack encoding format directly into the output stream,
- * without incurring decompression and recompression overheads.
+ * interface to support
+ * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} with a means of
+ * copying an object that is already in pack encoding format directly into the
+ * output stream, without incurring decompression and recompression overheads.
  */
 public interface ObjectReuseAsIs {
 	/**
 	 * Allocate a new {@code PackWriter} state structure for an object.
 	 * <p>
-	 * {@link PackWriter} allocates these objects to keep track of the
-	 * per-object state, and how to load the objects efficiently into the
-	 * generated stream. Implementers may subclass this type with additional
-	 * object state, such as to remember what file and offset contains the
-	 * object's pack encoded data.
+	 * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} allocates these
+	 * objects to keep track of the per-object state, and how to load the
+	 * objects efficiently into the generated stream. Implementers may subclass
+	 * this type with additional object state, such as to remember what file and
+	 * offset contains the object's pack encoded data.
 	 *
 	 * @param objectId
 	 *            the id of the object that will be packed.
@@ -85,15 +86,16 @@ public interface ObjectReuseAsIs {
 	 * <p>
 	 * Implementations should iterate through all available representations of
 	 * an object, and pass them in turn to the PackWriter though
-	 * {@link PackWriter#select(ObjectToPack, StoredObjectRepresentation)} so
-	 * the writer can select the most suitable representation to reuse into the
-	 * output stream.
+	 * {@link org.eclipse.jgit.internal.storage.pack.PackWriter#select(ObjectToPack, StoredObjectRepresentation)}
+	 * so the writer can select the most suitable representation to reuse into
+	 * the output stream.
 	 * <p>
-	 * If the implementation returns CachedPack from {@link #getCachedPacksAndUpdate(BitmapBuilder)}
-	 * it must consider the representation of any object that is stored in any
-	 * of the offered CachedPacks. PackWriter relies on this behavior to prune
-	 * duplicate objects out of the pack stream when it selects a CachedPack and
-	 * the object was also reached through the thin-pack enumeration.
+	 * If the implementation returns CachedPack from
+	 * {@link #getCachedPacksAndUpdate(BitmapBuilder)} it must consider the
+	 * representation of any object that is stored in any of the offered
+	 * CachedPacks. PackWriter relies on this behavior to prune duplicate
+	 * objects out of the pack stream when it selects a CachedPack and the
+	 * object was also reached through the thin-pack enumeration.
 	 * <p>
 	 * The implementation may choose to consider multiple objects at once on
 	 * concurrent threads, but must evaluate all representations of an object
@@ -106,10 +108,10 @@ public interface ObjectReuseAsIs {
 	 *            once for each item in the iteration when selection is done.
 	 * @param objects
 	 *            the objects that are being packed.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             there is no representation available for the object, as it is
 	 *             no longer in the repository. Packing will abort.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the repository cannot be accessed. Packing will abort.
 	 */
 	public void selectObjectRepresentation(PackWriter packer,
@@ -136,7 +138,9 @@ public interface ObjectReuseAsIs {
 	 * format to reach a delta base that is later in the stream. It may also
 	 * reduce data locality for the reader, slowing down data access.
 	 *
-	 * Invoking {@link PackOutputStream#writeObject(ObjectToPack)} will cause
+	 * Invoking
+	 * {@link org.eclipse.jgit.internal.storage.pack.PackOutputStream#writeObject(ObjectToPack)}
+	 * will cause
 	 * {@link #copyObjectAsIs(PackOutputStream, ObjectToPack, boolean)} to be
 	 * invoked recursively on {@code this} if the current object is scheduled
 	 * for reuse.
@@ -147,7 +151,7 @@ public interface ObjectReuseAsIs {
 	 *            the list of objects to write. Objects should be written in
 	 *            approximately this order. Implementors may resort the list
 	 *            elements in-place during writing if desired.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the stream cannot be written to, or one or more required
 	 *             objects cannot be accessed from the object database.
 	 */
@@ -186,13 +190,13 @@ public interface ObjectReuseAsIs {
 	 *            corrupt before being reused. If false, validation may be
 	 *            skipped as it will be performed elsewhere in the processing
 	 *            pipeline.
-	 * @throws StoredObjectRepresentationNotAvailableException
+	 * @throws org.eclipse.jgit.errors.StoredObjectRepresentationNotAvailableException
 	 *             the previously selected representation is no longer
 	 *             available. If thrown before {@code out.writeHeader} the pack
 	 *             writer will try to find another representation, and write
 	 *             that one instead. If throw after {@code out.writeHeader},
 	 *             packing will abort.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the stream's write method threw an exception. Packing will
 	 *             abort.
 	 */
@@ -209,7 +213,7 @@ public interface ObjectReuseAsIs {
 	 *            stream to append the pack onto.
 	 * @param pack
 	 *            the cached pack to send.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the pack cannot be read, or stream did not accept a write.
 	 */
 	public abstract void copyPackAsIs(PackOutputStream out, CachedPack pack)
@@ -225,7 +229,7 @@ public interface ObjectReuseAsIs {
 	 * @param needBitmap
 	 *            the bitmap that contains all of the objects the client wants.
 	 * @return the available cached packs.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the cached packs cannot be listed from the repository.
 	 *             Callers may choose to ignore this and continue as-if there
 	 *             were no cached packs.

org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectToPack.java

@@ -50,7 +50,8 @@ import org.eclipse.jgit.lib.ObjectId;
 import org.eclipse.jgit.transport.PackedObjectInfo;
 
 /**
- * Per-object state used by {@link PackWriter}.
+ * Per-object state used by
+ * {@link org.eclipse.jgit.internal.storage.pack.PackWriter}.
  * <p>
  * {@code PackWriter} uses this class to track the things it needs to include in
  * the newly generated pack file, and how to efficiently obtain the raw data for
@@ -108,19 +109,25 @@ public class ObjectToPack extends PackedObjectInfo {
 	}
 
 	/**
+	 * Get delta base object id if object is going to be packed in delta
+	 * representation
+	 *
 	 * @return delta base object id if object is going to be packed in delta
-	 *         representation; null otherwise - if going to be packed as a
-	 *         whole object.
+	 *         representation; null otherwise - if going to be packed as a whole
+	 *         object.
 	 */
 	public final ObjectId getDeltaBaseId() {
 		return deltaBase;
 	}
 
 	/**
+	 * Get delta base object to pack if object is going to be packed in delta
+	 * representation and delta is specified as object to pack
+	 *
 	 * @return delta base object to pack if object is going to be packed in
-	 *         delta representation and delta is specified as object to
-	 *         pack; null otherwise - if going to be packed as a whole
-	 *         object or delta base is specified only as id.
+	 *         delta representation and delta is specified as object to pack;
+	 *         null otherwise - if going to be packed as a whole object or delta
+	 *         base is specified only as id.
 	 */
 	public final ObjectToPack getDeltaBase() {
 		if (deltaBase instanceof ObjectToPack)
@@ -164,8 +171,9 @@ public class ObjectToPack extends PackedObjectInfo {
 	}
 
 	/**
-	 * @return true if object is going to be written as delta; false
-	 *         otherwise.
+	 * Whether object is going to be written as delta
+	 *
+	 * @return true if object is going to be written as delta; false otherwise.
 	 */
 	public final boolean isDeltaRepresentation() {
 		return deltaBase != null;
@@ -181,7 +189,7 @@ public class ObjectToPack extends PackedObjectInfo {
 		return 1 < getOffset(); // markWantWrite sets 1.
 	}
 
-	/** @return the type of this object. */
+	/** {@inheritDoc} */
 	@Override
 	public final int getType() {
 		return (flags >> TYPE_SHIFT) & 0x7;
@@ -216,6 +224,9 @@ public class ObjectToPack extends PackedObjectInfo {
 	}
 
 	/**
+	 * Whether an existing representation was selected to be reused as-is into
+	 * the pack stream.
+	 *
 	 * @return true if an existing representation was selected to be reused
 	 *         as-is into the pack stream.
 	 */
@@ -266,7 +277,11 @@ public class ObjectToPack extends PackedObjectInfo {
 			flags &= ~DELTA_ATTEMPTED;
 	}
 
-	/** @return the extended flags on this object, in the range [0x0, 0xf]. */
+	/**
+	 * Get the extended flags on this object, in the range [0x0, 0xf].
+	 *
+	 * @return the extended flags on this object, in the range [0x0, 0xf].
+	 */
 	protected final int getExtendedFlags() {
 		return (flags >>> EXT_SHIFT) & EXT_MASK;
 	}
@@ -363,9 +378,10 @@ public class ObjectToPack extends PackedObjectInfo {
 	 * Remember a specific representation for reuse at a later time.
 	 * <p>
 	 * Implementers should remember the representation chosen, so it can be
-	 * reused at a later time. {@link PackWriter} may invoke this method
-	 * multiple times for the same object, each time saving the current best
-	 * representation found.
+	 * reused at a later time.
+	 * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} may invoke this
+	 * method multiple times for the same object, each time saving the current
+	 * best representation found.
 	 *
 	 * @param ref
 	 *            the object representation.
@@ -374,6 +390,7 @@ public class ObjectToPack extends PackedObjectInfo {
 		// Empty by default.
 	}
 
+	/** {@inheritDoc} */
 	@SuppressWarnings("nls")
 	@Override
 	public String toString() {

org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackExt.java

@@ -43,7 +43,9 @@
 
 package org.eclipse.jgit.internal.storage.pack;
 
-/** A pack file extension. */
+/**
+ * A pack file extension.
+ */
 public class PackExt {
 	private static volatile PackExt[] VALUES = new PackExt[] {};
 
@@ -62,7 +64,11 @@ public class PackExt {
 	/** A reftable file. */
 	public static final PackExt REFTABLE = newPackExt("ref"); //$NON-NLS-1$
 
-	/** @return all of the PackExt values. */
+	/**
+	 * Get all of the PackExt values.
+	 *
+	 * @return all of the PackExt values.
+	 */
 	public static PackExt[] values() {
 		return VALUES;
 	}
@@ -102,21 +108,34 @@ public class PackExt {
 		this.pos = pos;
 	}
 
-	/** @return the file extension. */
+	/**
+	 * Get the file extension.
+	 *
+	 * @return the file extension.
+	 */
 	public String getExtension() {
 		return ext;
 	}
 
-	/** @return the position of the extension in the values array. */
+	/**
+	 * Get the position of the extension in the values array.
+	 *
+	 * @return the position of the extension in the values array.
+	 */
 	public int getPosition() {
 		return pos;
 	}
 
-	/** @return the bit mask of the extension e.g {@code 1 << getPosition()}. */
+	/**
+	 * Get the bit mask of the extension e.g {@code 1 << getPosition()}.
+	 *
+	 * @return the bit mask of the extension e.g {@code 1 << getPosition()}.
+	 */
 	public int getBit() {
 		return 1 << getPosition();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		return String.format("PackExt[%s, bit=0x%s]", getExtension(), //$NON-NLS-1$

org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackOutputStream.java

@@ -57,7 +57,10 @@ import org.eclipse.jgit.lib.Constants;
 import org.eclipse.jgit.lib.ProgressMonitor;
 import org.eclipse.jgit.util.NB;
 
-/** Custom output stream to support {@link PackWriter}. */
+/**
+ * Custom output stream to support
+ * {@link org.eclipse.jgit.internal.storage.pack.PackWriter}.
+ */
 public final class PackOutputStream extends OutputStream {
 	private static final int BYTES_TO_WRITE_BEFORE_CANCEL_CHECK = 128 * 1024;
 
@@ -84,7 +87,8 @@ public final class PackOutputStream extends OutputStream {
 	 * <p>
 	 * This constructor is exposed to support debugging the JGit library only.
 	 * Application or storage level code should not create a PackOutputStream,
-	 * instead use {@link PackWriter}, and let the writer create the stream.
+	 * instead use {@link org.eclipse.jgit.internal.storage.pack.PackWriter},
+	 * and let the writer create the stream.
 	 *
 	 * @param writeMonitor
 	 *            monitor to update on object output progress.
@@ -101,6 +105,7 @@ public final class PackOutputStream extends OutputStream {
 		this.checkCancelAt = BYTES_TO_WRITE_BEFORE_CANCEL_CHECK;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public final void write(final int b) throws IOException {
 		count++;
@@ -108,6 +113,7 @@ public final class PackOutputStream extends OutputStream {
 		md.update((byte) b);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public final void write(final byte[] b, int off, int len)
 			throws IOException {
@@ -131,6 +137,7 @@ public final class PackOutputStream extends OutputStream {
 		}
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void flush() throws IOException {
 		out.flush();
@@ -154,7 +161,7 @@ public final class PackOutputStream extends OutputStream {
 	 *
 	 * @param otp
 	 *            the object to write.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the object cannot be read from the object reader, or the
 	 *             output stream is no longer accepting output. Caller must
 	 *             examine the type of exception and possibly its message to
@@ -177,7 +184,7 @@ public final class PackOutputStream extends OutputStream {
 	 *            in whole object format, this is the same as the object size.
 	 *            For an object that is in a delta format, this is the size of
 	 *            the inflated delta instruction stream.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the underlying stream refused to accept the header.
 	 */
 	public final void writeHeader(ObjectToPack otp, long rawLength)
@@ -224,7 +231,11 @@ public final class PackOutputStream extends OutputStream {
 		return n;
 	}
 
-	/** @return a temporary buffer writers can use to copy data with. */
+	/**
+	 * Get a temporary buffer writers can use to copy data with.
+	 *
+	 * @return a temporary buffer writers can use to copy data with.
+	 */
 	public final byte[] getCopyBuffer() {
 		return copyBuffer;
 	}
@@ -233,7 +244,11 @@ public final class PackOutputStream extends OutputStream {
 		writeMonitor.update(1);
 	}
 
-	/** @return total number of bytes written since stream start. */
+	/**
+	 * Get total number of bytes written since stream start.
+	 *
+	 * @return total number of bytes written since stream start.
+	 */
 	public final long length() {
 		return count;
 	}

org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriter.java

@@ -135,8 +135,8 @@ import org.eclipse.jgit.util.TemporaryBuffer;
  * <li>(usually) by providing sets of interesting and uninteresting objects in
  * repository - all interesting objects and their ancestors except uninteresting
  * objects and their ancestors will be included in pack, or</li>
- * <li>by providing iterator of {@link RevObject} specifying exact list and
- * order of objects in pack</li>
+ * <li>by providing iterator of {@link org.eclipse.jgit.revwalk.RevObject}
+ * specifying exact list and order of objects in pack</li>
  * </ul>
  * <p>
  * Typical usage consists of creating an instance, configuring options,
@@ -149,10 +149,11 @@ import org.eclipse.jgit.util.TemporaryBuffer;
  * followed by {@link #writeBitmapIndex(OutputStream)}.
  * </p>
  * <p>
- * Class provide set of configurable options and {@link ProgressMonitor}
- * support, as operations may take a long time for big repositories. Deltas
- * searching algorithm is <b>NOT IMPLEMENTED</b> yet - this implementation
- * relies only on deltas and objects reuse.
+ * Class provide set of configurable options and
+ * {@link org.eclipse.jgit.lib.ProgressMonitor} support, as operations may take
+ * a long time for big repositories. Deltas searching algorithm is <b>NOT
+ * IMPLEMENTED</b> yet - this implementation relies only on deltas and objects
+ * reuse.
  * </p>
  * <p>
  * This class is not thread safe. It is intended to be used in one thread as a
@@ -210,7 +211,11 @@ public class PackWriter implements AutoCloseable {
 		}
 	};
 
-	/** @return all allocated, non-released PackWriters instances. */
+	/**
+	 * Get all allocated, non-released PackWriters instances.
+	 *
+	 * @return all allocated, non-released PackWriters instances.
+	 */
 	public static Iterable<PackWriter> getInstances() {
 		return instancesIterable;
 	}
@@ -374,7 +379,6 @@ public class PackWriter implements AutoCloseable {
 	 *
 	 * @param callback
 	 *            the callback to set
-	 *
 	 * @return this object for chaining.
 	 */
 	public PackWriter setObjectCountCallback(ObjectCountCallback callback) {
@@ -466,12 +470,19 @@ public class PackWriter implements AutoCloseable {
 		reuseValidate = validate;
 	}
 
-	/** @return true if this writer is producing a thin pack. */
+	/**
+	 * Whether this writer is producing a thin pack.
+	 *
+	 * @return true if this writer is producing a thin pack.
+	 */
 	public boolean isThin() {
 		return thin;
 	}
 
 	/**
+	 * Whether writer may pack objects with delta base object not within set of
+	 * objects to pack
+	 *
 	 * @param packthin
 	 *            a boolean indicating whether writer may pack objects with
 	 *            delta base object not within set of objects to pack, but
@@ -483,16 +494,23 @@ public class PackWriter implements AutoCloseable {
 		thin = packthin;
 	}
 
-	/** @return true to reuse cached packs. If true index creation isn't available. */
+	/**
+	 * Whether to reuse cached packs.
+	 *
+	 * @return {@code true} to reuse cached packs. If true index creation isn't
+	 *         available.
+	 */
 	public boolean isUseCachedPacks() {
 		return useCachedPacks;
 	}
 
 	/**
+	 * Whether to use cached packs
+	 *
 	 * @param useCached
-	 *            if set to true and a cached pack is present, it will be
-	 *            appended onto the end of a thin-pack, reducing the amount of
-	 *            working set space and CPU used by PackWriter. Enabling this
+	 *            if set to {@code true} and a cached pack is present, it will
+	 *            be appended onto the end of a thin-pack, reducing the amount
+	 *            of working set space and CPU used by PackWriter. Enabling this
 	 *            feature prevents PackWriter from creating an index for the
 	 *            newly created pack, so its only suitable for writing to a
 	 *            network client, where the client will make the index.
@@ -501,12 +519,18 @@ public class PackWriter implements AutoCloseable {
 		useCachedPacks = useCached;
 	}
 
-	/** @return true to use bitmaps for ObjectWalks, if available. */
+	/**
+	 * Whether to use bitmaps
+	 *
+	 * @return {@code true} to use bitmaps for ObjectWalks, if available.
+	 */
 	public boolean isUseBitmaps() {
 		return useBitmaps;
 	}
 
 	/**
+	 * Whether to use bitmaps
+	 *
 	 * @param useBitmaps
 	 *            if set to true, bitmaps will be used when preparing a pack.
 	 */
@@ -514,23 +538,33 @@ public class PackWriter implements AutoCloseable {
 		this.useBitmaps = useBitmaps;
 	}
 
-	/** @return true if the index file cannot be created by this PackWriter. */
+	/**
+	 * Whether the index file cannot be created by this PackWriter.
+	 *
+	 * @return {@code true} if the index file cannot be created by this
+	 *         PackWriter.
+	 */
 	public boolean isIndexDisabled() {
 		return indexDisabled || !cachedPacks.isEmpty();
 	}
 
 	/**
+	 * Whether to disable creation of the index file.
+	 *
 	 * @param noIndex
-	 *            true to disable creation of the index file.
+	 *            {@code true} to disable creation of the index file.
 	 */
 	public void setIndexDisabled(boolean noIndex) {
 		this.indexDisabled = noIndex;
 	}
 
 	/**
-	 * @return true to ignore objects that are uninteresting and also not found
-	 *         on local disk; false to throw a {@link MissingObjectException}
-	 *         out of {@link #preparePack(ProgressMonitor, Set, Set)} if an
+	 * Whether to ignore missing uninteresting objects
+	 *
+	 * @return {@code true} to ignore objects that are uninteresting and also
+	 *         not found on local disk; false to throw a
+	 *         {@link org.eclipse.jgit.errors.MissingObjectException} out of
+	 *         {@link #preparePack(ProgressMonitor, Set, Set)} if an
 	 *         uninteresting object is not in the source repository. By default,
 	 *         true, permitting gracefully ignoring of uninteresting objects.
 	 */
@@ -539,11 +573,13 @@ public class PackWriter implements AutoCloseable {
 	}
 
 	/**
+	 * Whether writer should ignore non existing uninteresting objects
+	 *
 	 * @param ignore
-	 *            true if writer should ignore non existing uninteresting
-	 *            objects during construction set of objects to pack; false
-	 *            otherwise - non existing uninteresting objects may cause
-	 *            {@link MissingObjectException}
+	 *            {@code true} if writer should ignore non existing
+	 *            uninteresting objects during construction set of objects to
+	 *            pack; false otherwise - non existing uninteresting objects may
+	 *            cause {@link org.eclipse.jgit.errors.MissingObjectException}
 	 */
 	public void setIgnoreMissingUninteresting(final boolean ignore) {
 		ignoreMissingUninteresting = ignore;
@@ -586,7 +622,7 @@ public class PackWriter implements AutoCloseable {
 	 * Returns objects number in a pack file that was created by this writer.
 	 *
 	 * @return number of objects in pack.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a cached pack cannot supply its object count.
 	 */
 	public long getObjectCount() throws IOException {
@@ -613,7 +649,7 @@ public class PackWriter implements AutoCloseable {
 	 * been invoked and completed successfully.
 	 *
 	 * @return set of objects in pack.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a cached pack cannot supply its object ids.
 	 */
 	public ObjectIdOwnerMap<ObjectIdOwnerMap.Entry> getObjectSet()
@@ -672,12 +708,14 @@ public class PackWriter implements AutoCloseable {
 	 * @param objectsSource
 	 *            iterator of object to store in a pack; order of objects within
 	 *            each type is important, ordering by type is not needed;
-	 *            allowed types for objects are {@link Constants#OBJ_COMMIT},
-	 *            {@link Constants#OBJ_TREE}, {@link Constants#OBJ_BLOB} and
-	 *            {@link Constants#OBJ_TAG}; objects returned by iterator may be
-	 *            later reused by caller as object id and type are internally
-	 *            copied in each iteration.
-	 * @throws IOException
+	 *            allowed types for objects are
+	 *            {@link org.eclipse.jgit.lib.Constants#OBJ_COMMIT},
+	 *            {@link org.eclipse.jgit.lib.Constants#OBJ_TREE},
+	 *            {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB} and
+	 *            {@link org.eclipse.jgit.lib.Constants#OBJ_TAG}; objects
+	 *            returned by iterator may be later reused by caller as object
+	 *            id and type are internally copied in each iteration.
+	 * @throws java.io.IOException
 	 *             when some I/O problem occur during reading objects.
 	 */
 	public void preparePack(@NonNull Iterator<RevObject> objectsSource)
@@ -693,10 +731,10 @@ public class PackWriter implements AutoCloseable {
 	 * Basing on these 2 sets, another set of objects to put in a pack file is
 	 * created: this set consists of all objects reachable (ancestors) from
 	 * interesting objects, except uninteresting objects and their ancestors.
-	 * This method uses class {@link ObjectWalk} extensively to find out that
-	 * appropriate set of output objects and their optimal order in output pack.
-	 * Order is consistent with general git in-pack rules: sort by object type,
-	 * recency, path and delta-base first.
+	 * This method uses class {@link org.eclipse.jgit.revwalk.ObjectWalk}
+	 * extensively to find out that appropriate set of output objects and their
+	 * optimal order in output pack. Order is consistent with general git
+	 * in-pack rules: sort by object type, recency, path and delta-base first.
 	 * </p>
 	 *
 	 * @param countingMonitor
@@ -709,7 +747,7 @@ public class PackWriter implements AutoCloseable {
 	 *            points of graph traversal). Pass {@link #NONE} if all objects
 	 *            reachable from {@code want} are desired, such as when serving
 	 *            a clone.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             when some I/O problem occur during reading objects.
 	 */
 	public void preparePack(ProgressMonitor countingMonitor,
@@ -744,7 +782,7 @@ public class PackWriter implements AutoCloseable {
 	 *            {@code shallow} commits and earlier generations will be
 	 *            included in the pack if requested by {@code want}. Must not be
 	 *            {@code null}.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             an I/O problem occurred while reading objects.
 	 */
 	public void preparePack(ProgressMonitor countingMonitor,
@@ -783,7 +821,7 @@ public class PackWriter implements AutoCloseable {
 	 * @param noBitmaps
 	 *            collection of objects to be excluded from bitmap commit
 	 *            selection.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             an I/O problem occurred while reading objects.
 	 */
 	public void preparePack(ProgressMonitor countingMonitor,
@@ -808,10 +846,10 @@ public class PackWriter implements AutoCloseable {
 	 * Basing on these 2 sets, another set of objects to put in a pack file is
 	 * created: this set consists of all objects reachable (ancestors) from
 	 * interesting objects, except uninteresting objects and their ancestors.
-	 * This method uses class {@link ObjectWalk} extensively to find out that
-	 * appropriate set of output objects and their optimal order in output pack.
-	 * Order is consistent with general git in-pack rules: sort by object type,
-	 * recency, path and delta-base first.
+	 * This method uses class {@link org.eclipse.jgit.revwalk.ObjectWalk}
+	 * extensively to find out that appropriate set of output objects and their
+	 * optimal order in output pack. Order is consistent with general git
+	 * in-pack rules: sort by object type, recency, path and delta-base first.
 	 * </p>
 	 *
 	 * @param countingMonitor
@@ -829,7 +867,7 @@ public class PackWriter implements AutoCloseable {
 	 * @param noBitmaps
 	 *            collection of objects to be excluded from bitmap commit
 	 *            selection.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             when some I/O problem occur during reading objects.
 	 */
 	public void preparePack(ProgressMonitor countingMonitor,
@@ -853,7 +891,7 @@ public class PackWriter implements AutoCloseable {
 	 * @param id
 	 *            the object to test the existence of.
 	 * @return true if the object will appear in the output pack file.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a cached pack cannot be examined.
 	 */
 	public boolean willInclude(final AnyObjectId id) throws IOException {
@@ -920,7 +958,7 @@ public class PackWriter implements AutoCloseable {
 	 * @param indexStream
 	 *            output for the index data. Caller is responsible for closing
 	 *            this stream.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the index data could not be written to the supplied stream.
 	 */
 	public void writeIndex(final OutputStream indexStream) throws IOException {
@@ -942,7 +980,7 @@ public class PackWriter implements AutoCloseable {
 	 * @param bitmapIndexStream
 	 *            output for the bitmap index data. Caller is responsible for
 	 *            closing this stream.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the index data could not be written to the supplied stream.
 	 */
 	public void writeBitmapIndex(final OutputStream bitmapIndexStream)
@@ -1027,13 +1065,13 @@ public class PackWriter implements AutoCloseable {
 	 * @param packStream
 	 *            output stream of pack data. The stream should be buffered by
 	 *            the caller. The caller is responsible for closing the stream.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             an error occurred reading a local object's data to include in
 	 *             the pack, or writing compressed object data to the output
 	 *             stream.
 	 * @throws WriteAbortedException
-	 *             the write operation is aborted by {@link ObjectCountCallback}
-	 *             .
+	 *             the write operation is aborted by
+	 *             {@link org.eclipse.jgit.transport.ObjectCountCallback} .
 	 */
 	public void writePack(ProgressMonitor compressMonitor,
 			ProgressMonitor writeMonitor, OutputStream packStream)
@@ -1122,6 +1160,9 @@ public class PackWriter implements AutoCloseable {
 	}
 
 	/**
+	 * Get statistics of what this PackWriter did in order to create the final
+	 * pack stream.
+	 *
 	 * @return description of what this PackWriter did in order to create the
 	 *         final pack stream. This should only be invoked after the calls to
 	 *         create the pack/index/bitmap have completed.
@@ -1130,12 +1171,18 @@ public class PackWriter implements AutoCloseable {
 		return new PackStatistics(stats);
 	}
 
-	/** @return snapshot of the current state of this PackWriter. */
+	/**
+	 * Get snapshot of the current state of this PackWriter.
+	 *
+	 * @return snapshot of the current state of this PackWriter.
+	 */
 	public State getState() {
 		return state.snapshot();
 	}
 
 	/**
+	 * {@inheritDoc}
+	 * <p>
 	 * Release all resources used by this writer.
 	 */
 	@Override
@@ -1972,7 +2019,7 @@ public class PackWriter implements AutoCloseable {
 	 *
 	 * @param object
 	 *            the object to add.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             the object is an unsupported type.
 	 */
 	public void addObject(final RevObject object)
@@ -2014,9 +2061,9 @@ public class PackWriter implements AutoCloseable {
 	/**
 	 * Select an object representation for this writer.
 	 * <p>
-	 * An {@link ObjectReader} implementation should invoke this method once for
-	 * each representation available for an object, to allow the writer to find
-	 * the most suitable one for the output.
+	 * An {@link org.eclipse.jgit.lib.ObjectReader} implementation should invoke
+	 * this method once for each representation available for an object, to
+	 * allow the writer to find the most suitable one for the output.
 	 *
 	 * @param otp
 	 *            the object being packed.
@@ -2097,7 +2144,7 @@ public class PackWriter implements AutoCloseable {
 	 * @param pm
 	 *            progress monitor to report bitmap building work.
 	 * @return whether a bitmap index may be written.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             when some I/O problem occur during reading objects.
 	 */
 	public boolean prepareBitmapIndex(ProgressMonitor pm) throws IOException {

org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/StoredObjectRepresentation.java

@@ -46,7 +46,9 @@ package org.eclipse.jgit.internal.storage.pack;
 import org.eclipse.jgit.lib.ObjectId;
 
 /**
- * An object representation {@link PackWriter} can consider for packing.
+ * An object representation
+ * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} can consider for
+ * packing.
  */
 public class StoredObjectRepresentation {
 	/** Special unknown value for {@link #getWeight()}. */
@@ -62,6 +64,8 @@ public class StoredObjectRepresentation {
 	public static final int FORMAT_OTHER = 2;
 
 	/**
+	 * Get relative size of this object's packed form.
+	 *
 	 * @return relative size of this object's packed form. The special value
 	 *         {@link #WEIGHT_UNKNOWN} can be returned to indicate the
 	 *         implementation doesn't know, or cannot supply the weight up
@@ -72,6 +76,8 @@ public class StoredObjectRepresentation {
 	}
 
 	/**
+	 * Get the storage format type
+	 *
 	 * @return the storage format type, which must be one of
 	 *         {@link #PACK_DELTA}, {@link #PACK_WHOLE}, or
 	 *         {@link #FORMAT_OTHER}.
@@ -81,6 +87,9 @@ public class StoredObjectRepresentation {
 	}
 
 	/**
+	 * Get identity of the object this delta applies to in order to recover the
+	 * original object content.
+	 *
 	 * @return identity of the object this delta applies to in order to recover
 	 *         the original object content. This method should only be called if
 	 *         {@link #getFormat()} returned {@link #PACK_DELTA}.
@@ -90,6 +99,9 @@ public class StoredObjectRepresentation {
 	}
 
 	/**
+	 * Whether the current representation of the object has had delta
+	 * compression attempted on it.
+	 *
 	 * @return whether the current representation of the object has had delta
 	 *         compression attempted on it.
 	 */