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

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

5 files changed, 169 insertions, 41 deletions

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileBasedConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileBasedConfig.java
index ba62418e1d..32a8bfdbb9 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileBasedConfig.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileBasedConfig.java
@@ -115,27 +115,29 @@ public class FileBasedConfig extends StoredConfig {
 		this.hash = ObjectId.zeroId();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	protected boolean notifyUponTransientChanges() {
 		// we will notify listeners upon save()
 		return false;
 	}
 
-	/** @return location of the configuration file on disk */
+	/**
+	 * Get location of the configuration file on disk
+	 *
+	 * @return location of the configuration file on disk
+	 */
 	public final File getFile() {
 		return configFile;
 	}
 
 	/**
+	 * {@inheritDoc}
+	 * <p>
 	 * Load the configuration as a Git text style configuration file.
 	 * <p>
 	 * If the file does not exist, this configuration is cleared, and thus
 	 * behaves the same as though the file exists, but is empty.
-	 *
-	 * @throws IOException
-	 *             the file could not be read (but does exist).
-	 * @throws ConfigInvalidException
-	 *             the file is not a properly formatted configuration file.
 	 */
 	@Override
 	public void load() throws IOException, ConfigInvalidException {
@@ -178,6 +180,8 @@ public class FileBasedConfig extends StoredConfig {
 	}
 
 	/**
+	 * {@inheritDoc}
+	 * <p>
 	 * Save the configuration as a Git text style configuration file.
 	 * <p>
 	 * <b>Warning:</b> Although this method uses the traditional Git file
@@ -185,9 +189,6 @@ public class FileBasedConfig extends StoredConfig {
 	 * configuration file, it does not ensure that the file has not been
 	 * modified since the last read, which means updates performed by other
 	 * objects accessing the same backing file may be lost.
-	 *
-	 * @throws IOException
-	 *             the file could not be written.
 	 */
 	@Override
 	public void save() throws IOException {
@@ -221,6 +222,7 @@ public class FileBasedConfig extends StoredConfig {
 		fireConfigChangedEvent();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void clear() {
 		hash = hash(new byte[0]);
@@ -231,6 +233,7 @@ public class FileBasedConfig extends StoredConfig {
 		return ObjectId.fromRaw(Constants.newMessageDigest().digest(rawText));
 	}
 
+	/** {@inheritDoc} */
 	@SuppressWarnings("nls")
 	@Override
 	public String toString() {
@@ -238,14 +241,18 @@ public class FileBasedConfig extends StoredConfig {
 	}
 
 	/**
+	 * Whether the currently loaded configuration file is outdated
+	 *
 	 * @return returns true if the currently loaded configuration file is older
-	 * than the file on disk
+	 *         than the file on disk
 	 */
 	public boolean isOutdated() {
 		return snapshot.isModified(getFile());
 	}
 
 	/**
+	 * {@inheritDoc}
+	 *
 	 * @since 4.10
 	 */
 	@Override
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileRepositoryBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileRepositoryBuilder.java
index 944fb4f5ea..3e45bd5ce8 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileRepositoryBuilder.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileRepositoryBuilder.java
@@ -52,7 +52,7 @@ import org.eclipse.jgit.lib.BaseRepositoryBuilder;
 import org.eclipse.jgit.lib.Repository;
 
 /**
- * Constructs a {@link FileRepository}.
+ * Constructs a {@link org.eclipse.jgit.internal.storage.file.FileRepository}.
  * <p>
  * Applications must set one of {@link #setGitDir(File)} or
  * {@link #setWorkTree(File)}, or use {@link #readEnvironment()} or
@@ -73,18 +73,14 @@ import org.eclipse.jgit.lib.Repository;
 public class FileRepositoryBuilder extends
 		BaseRepositoryBuilder<FileRepositoryBuilder, Repository> {
 	/**
+	 * {@inheritDoc}
+	 * <p>
 	 * Create a repository matching the configuration in this builder.
 	 * <p>
 	 * If an option was not set, the build method will try to default the option
 	 * based on other options. If insufficient information is available, an
 	 * exception is thrown to the caller.
 	 *
-	 * @return a repository matching this configuration.
-	 * @throws IllegalArgumentException
-	 *             insufficient parameters were set.
-	 * @throws IOException
-	 *             the repository could not be accessed to configure the rest of
-	 *             the builder's parameters.
 	 * @since 3.0
 	 */
 	@Override
@@ -96,12 +92,13 @@ public class FileRepositoryBuilder extends
 	}
 
 	/**
-	 * Convenience factory method to construct a {@link FileRepository}.
+	 * Convenience factory method to construct a
+	 * {@link org.eclipse.jgit.internal.storage.file.FileRepository}.
 	 *
 	 * @param gitDir
 	 *            {@code GIT_DIR}, the repository meta directory.
 	 * @return a repository matching this configuration.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the repository could not be accessed to configure the rest of
 	 *             the builder's parameters.
 	 * @since 3.0
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/WindowCacheConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/WindowCacheConfig.java
index 4205fc4e80..19fc63e00b 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/WindowCacheConfig.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/WindowCacheConfig.java
@@ -47,7 +47,9 @@ import org.eclipse.jgit.internal.storage.file.WindowCache;
 import org.eclipse.jgit.lib.Config;
 import org.eclipse.jgit.storage.pack.PackConfig;
 
-/** Configuration parameters for JVM-wide buffer cache used by JGit. */
+/**
+ * Configuration parameters for JVM-wide buffer cache used by JGit.
+ */
 public class WindowCacheConfig {
 	/** 1024 (number of bytes in one kibibyte/kilobyte) */
 	public static final int KB = 1024;
@@ -67,7 +69,9 @@ public class WindowCacheConfig {
 
 	private int streamFileThreshold;
 
-	/** Create a default configuration. */
+	/**
+	 * Create a default configuration.
+	 */
 	public WindowCacheConfig() {
 		packedGitOpenFiles = 128;
 		packedGitLimit = 10 * MB;
@@ -78,6 +82,8 @@ public class WindowCacheConfig {
 	}
 
 	/**
+	 * Get maximum number of streams to open at a time.
+	 *
 	 * @return maximum number of streams to open at a time. Open packs count
 	 *         against the process limits. <b>Default is 128.</b>
 	 */
@@ -86,6 +92,8 @@ public class WindowCacheConfig {
 	}
 
 	/**
+	 * Set maximum number of streams to open at a time.
+	 *
 	 * @param fdLimit
 	 *            maximum number of streams to open at a time. Open packs count
 	 *            against the process limits
@@ -95,6 +103,9 @@ public class WindowCacheConfig {
 	}
 
 	/**
+	 * Get maximum number bytes of heap memory to dedicate to caching pack file
+	 * data.
+	 *
 	 * @return maximum number bytes of heap memory to dedicate to caching pack
 	 *         file data. <b>Default is 10 MB.</b>
 	 */
@@ -103,6 +114,9 @@ public class WindowCacheConfig {
 	}
 
 	/**
+	 * Set maximum number bytes of heap memory to dedicate to caching pack file
+	 * data.
+	 *
 	 * @param newLimit
 	 *            maximum number bytes of heap memory to dedicate to caching
 	 *            pack file data.
@@ -112,6 +126,9 @@ public class WindowCacheConfig {
 	}
 
 	/**
+	 * Get size in bytes of a single window mapped or read in from the pack
+	 * file.
+	 *
 	 * @return size in bytes of a single window mapped or read in from the pack
 	 *         file. <b>Default is 8 KB.</b>
 	 */
@@ -120,6 +137,8 @@ public class WindowCacheConfig {
 	}
 
 	/**
+	 * Set size in bytes of a single window read in from the pack file.
+	 *
 	 * @param newSize
 	 *            size in bytes of a single window read in from the pack file.
 	 */
@@ -128,25 +147,32 @@ public class WindowCacheConfig {
 	}
 
 	/**
-	 * @return true enables use of Java NIO virtual memory mapping for windows;
-	 *         false reads entire window into a byte[] with standard read calls.
-	 *         <b>Default false.</b>
+	 * Whether to use Java NIO virtual memory mapping for windows
+	 *
+	 * @return {@code true} enables use of Java NIO virtual memory mapping for
+	 *         windows; false reads entire window into a byte[] with standard
+	 *         read calls. <b>Default false.</b>
 	 */
 	public boolean isPackedGitMMAP() {
 		return packedGitMMAP;
 	}
 
 	/**
+	 * Set whether to enable use of Java NIO virtual memory mapping for windows
+	 *
 	 * @param usemmap
-	 *            true enables use of Java NIO virtual memory mapping for
-	 *            windows; false reads entire window into a byte[] with standard
-	 *            read calls.
+	 *            {@code true} enables use of Java NIO virtual memory mapping
+	 *            for windows; false reads entire window into a byte[] with
+	 *            standard read calls.
 	 */
 	public void setPackedGitMMAP(final boolean usemmap) {
 		packedGitMMAP = usemmap;
 	}
 
 	/**
+	 * Get maximum number of bytes to cache in delta base cache for inflated,
+	 * recently accessed objects, without delta chains.
+	 *
 	 * @return maximum number of bytes to cache in delta base cache for
 	 *         inflated, recently accessed objects, without delta chains.
 	 *         <b>Default 10 MB.</b>
@@ -156,6 +182,9 @@ public class WindowCacheConfig {
 	}
 
 	/**
+	 * Set maximum number of bytes to cache in delta base cache for inflated,
+	 * recently accessed objects, without delta chains.
+	 *
 	 * @param newLimit
 	 *            maximum number of bytes to cache in delta base cache for
 	 *            inflated, recently accessed objects, without delta chains.
@@ -164,12 +193,18 @@ public class WindowCacheConfig {
 		deltaBaseCacheLimit = newLimit;
 	}
 
-	/** @return the size threshold beyond which objects must be streamed. */
+	/**
+	 * Get the size threshold beyond which objects must be streamed.
+	 *
+	 * @return the size threshold beyond which objects must be streamed.
+	 */
 	public int getStreamFileThreshold() {
 		return streamFileThreshold;
 	}
 
 	/**
+	 * Set new byte limit for objects that must be streamed.
+	 *
 	 * @param newLimit
 	 *            new byte limit for objects that must be streamed. Objects
 	 *            smaller than this size can be obtained as a contiguous byte
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackConfig.java
index 4f2374ff7b..484cde29ee 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackConfig.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackConfig.java
@@ -262,7 +262,9 @@ public class PackConfig {
 
 	private boolean singlePack;
 
-	/** Create a default configuration. */
+	/**
+	 * Create a default configuration.
+	 */
 	public PackConfig() {
 		// Fields are initialized to defaults.
 	}
@@ -280,7 +282,8 @@ public class PackConfig {
 	}
 
 	/**
-	 * 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
@@ -531,6 +534,9 @@ public class PackConfig {
 	}
 
 	/**
+	 * Whether existing delta chains should be cut at
+	 * {@link #getMaxDeltaDepth()}.
+	 *
 	 * @return true if existing delta chains should be cut at
 	 *         {@link #getMaxDeltaDepth()}. Default is false, allowing existing
 	 *         chains to be of any length.
@@ -558,9 +564,11 @@ public class PackConfig {
 	}
 
 	/**
+	 * Whether all of refs/* should be packed in a single pack.
+	 *
 	 * @return true if all of refs/* should be packed in a single pack. Default
-	 *        is false, packing a separate GC_REST pack for references outside
-	 *        of refs/heads/* and refs/tags/*.
+	 *         is false, packing a separate GC_REST pack for references outside
+	 *         of refs/heads/* and refs/tags/*.
 	 * @since 4.9
 	 */
 	public boolean getSinglePack() {
@@ -785,7 +793,11 @@ public class PackConfig {
 		this.threads = threads;
 	}
 
-	/** @return the preferred thread pool to execute delta search on. */
+	/**
+	 * Get the preferred thread pool to execute delta search on.
+	 *
+	 * @return the preferred thread pool to execute delta search on.
+	 */
 	public Executor getExecutor() {
 		return executor;
 	}
@@ -1073,6 +1085,7 @@ public class PackConfig {
 						getBitmapInactiveBranchAgeInDays()));
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		final StringBuilder b = new StringBuilder();
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackStatistics.java b/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackStatistics.java
index a811fe3cde..68cffd5b38 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackStatistics.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackStatistics.java
@@ -254,7 +254,8 @@ public class PackStatistics {
 	private Accumulator statistics;
 
 	/**
-	 * Creates a new {@link PackStatistics} object from the accumulator.
+	 * Creates a new {@link org.eclipse.jgit.storage.pack.PackStatistics} object
+	 * from the accumulator.
 	 *
 	 * @param accumulator
 	 *            the accumulator of the statistics
@@ -270,6 +271,8 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get unmodifiable collection of objects to be included in the pack.
+	 *
 	 * @return unmodifiable collection of objects to be included in the pack.
 	 *         May be {@code null} if the pack was hand-crafted in a unit test.
 	 */
@@ -278,6 +281,9 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get unmodifiable collection of objects that should be excluded from the
+	 * pack
+	 *
 	 * @return unmodifiable collection of objects that should be excluded from
 	 *         the pack, as the peer that will receive the pack already has
 	 *         these objects.
@@ -287,6 +293,9 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get unmodifiable collection of objects that were shallow commits on the
+	 * client.
+	 *
 	 * @return unmodifiable collection of objects that were shallow commits on
 	 *         the client.
 	 */
@@ -295,6 +304,8 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get unmodifiable list of the cached packs that were reused in the output
+	 *
 	 * @return unmodifiable list of the cached packs that were reused in the
 	 *         output, if any were selected for reuse.
 	 */
@@ -302,12 +313,19 @@ public class PackStatistics {
 		return statistics.reusedPacks;
 	}
 
-	/** @return unmodifiable collection of the root commits of the history. */
+	/**
+	 * Get unmodifiable collection of the root commits of the history.
+	 *
+	 * @return unmodifiable collection of the root commits of the history.
+	 */
 	public Set<ObjectId> getRootCommits() {
 		return statistics.rootCommits;
 	}
 
 	/**
+	 * Get number of objects in the output pack that went through the delta
+	 * search process in order to find a potential delta base.
+	 *
 	 * @return number of objects in the output pack that went through the delta
 	 *         search process in order to find a potential delta base.
 	 */
@@ -316,6 +334,9 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get number of objects in the output pack that went through delta base
+	 * search and found a suitable base.
+	 *
 	 * @return number of objects in the output pack that went through delta base
 	 *         search and found a suitable base. This is a subset of
 	 *         {@link #getDeltaSearchNonEdgeObjects()}.
@@ -325,6 +346,8 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get total number of objects output.
+	 *
 	 * @return total number of objects output. This total includes the value of
 	 *         {@link #getTotalDeltas()}.
 	 */
@@ -333,6 +356,9 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get the count of objects that needed to be discovered through an object
+	 * walk because they were not found in bitmap indices.
+	 *
 	 * @return the count of objects that needed to be discovered through an
 	 *         object walk because they were not found in bitmap indices.
 	 *         Returns -1 if no bitmap indices were found.
@@ -342,6 +368,8 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get total number of deltas output.
+	 *
 	 * @return total number of deltas output. This may be lower than the actual
 	 *         number of deltas if a cached pack was reused.
 	 */
@@ -350,6 +378,9 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get number of objects whose existing representation was reused in the
+	 * output.
+	 *
 	 * @return number of objects whose existing representation was reused in the
 	 *         output. This count includes {@link #getReusedDeltas()}.
 	 */
@@ -358,6 +389,9 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get number of deltas whose existing representation was reused in the
+	 * output.
+	 *
 	 * @return number of deltas whose existing representation was reused in the
 	 *         output, as their base object was also output or was assumed
 	 *         present for a thin pack. This may be lower than the actual number
@@ -368,6 +402,8 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get total number of bytes written.
+	 *
 	 * @return total number of bytes written. This size includes the pack
 	 *         header, trailer, thin pack, and reused cached pack(s).
 	 */
@@ -376,6 +412,8 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get size of the thin pack in bytes.
+	 *
 	 * @return size of the thin pack in bytes, if a thin pack was generated. A
 	 *         thin pack is created when the client already has objects and some
 	 *         deltas are created against those objects, or if a cached pack is
@@ -387,6 +425,8 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get information about this type of object in the pack.
+	 *
 	 * @param typeCode
 	 *            object type code, e.g. OBJ_COMMIT or OBJ_TREE.
 	 * @return information about this type of object in the pack.
@@ -395,17 +435,28 @@ public class PackStatistics {
 		return new ObjectType(statistics.objectTypes[typeCode]);
 	}
 
-	/** @return true if the resulting pack file was a shallow pack. */
+	/**
+	 * Whether the resulting pack file was a shallow pack.
+	 *
+	 * @return {@code true} if the resulting pack file was a shallow pack.
+	 */
 	public boolean isShallow() {
 		return statistics.depth > 0;
 	}
 
-	/** @return depth (in commits) the pack includes if shallow. */
+	/**
+	 * Get depth (in commits) the pack includes if shallow.
+	 *
+	 * @return depth (in commits) the pack includes if shallow.
+	 */
 	public int getDepth() {
 		return statistics.depth;
 	}
 
 	/**
+	 * Get time in milliseconds spent enumerating the objects that need to be
+	 * included in the output.
+	 *
 	 * @return time in milliseconds spent enumerating the objects that need to
 	 *         be included in the output. This time includes any restarts that
 	 *         occur when a cached pack is selected for reuse.
@@ -415,6 +466,9 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get time in milliseconds spent matching existing representations against
+	 * objects that will be transmitted.
+	 *
 	 * @return time in milliseconds spent matching existing representations
 	 *         against objects that will be transmitted, or that the client can
 	 *         be assumed to already have.
@@ -424,6 +478,9 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get time in milliseconds spent finding the sizes of all objects that will
+	 * enter the delta compression search window.
+	 *
 	 * @return time in milliseconds spent finding the sizes of all objects that
 	 *         will enter the delta compression search window. The sizes need to
 	 *         be known to better match similar objects together and improve
@@ -434,6 +491,8 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get time in milliseconds spent on delta compression.
+	 *
 	 * @return time in milliseconds spent on delta compression. This is observed
 	 *         wall-clock time and does not accurately track CPU time used when
 	 *         multiple threads were used to perform the delta compression.
@@ -443,6 +502,9 @@ public class PackStatistics {
 	}
 
 	/**
+	 * Get time in milliseconds spent writing the pack output, from start of
+	 * header until end of trailer.
+	 *
 	 * @return time in milliseconds spent writing the pack output, from start of
 	 *         header until end of trailer. The transfer speed can be
 	 *         approximated by dividing {@link #getTotalBytes()} by this value.
@@ -451,7 +513,11 @@ public class PackStatistics {
 		return statistics.timeWriting;
 	}
 
-	/** @return total time spent processing this pack. */
+	/**
+	 * Get total time spent processing this pack.
+	 *
+	 * @return total time spent processing this pack.
+	 */
 	public long getTimeTotal() {
 		return statistics.timeCounting + statistics.timeSearchingForReuse
 				+ statistics.timeSearchingForSizes + statistics.timeCompressing
@@ -459,14 +525,20 @@ public class PackStatistics {
 	}
 
 	/**
-	 * @return get the average output speed in terms of bytes-per-second.
+	 * Get the average output speed in terms of bytes-per-second.
+	 *
+	 * @return the average output speed in terms of bytes-per-second.
 	 *         {@code getTotalBytes() / (getTimeWriting() / 1000.0)}.
 	 */
 	public double getTransferRate() {
 		return getTotalBytes() / (getTimeWriting() / 1000.0);
 	}
 
-	/** @return formatted message string for display to clients. */
+	/**
+	 * Get formatted message string for display to clients.
+	 *
+	 * @return formatted message string for display to clients.
+	 */
 	public String getMessage() {
 		return MessageFormat.format(JGitText.get().packWriterStatistics,
 				Long.valueOf(statistics.totalObjects),
@@ -475,7 +547,11 @@ public class PackStatistics {
 				Long.valueOf(statistics.reusedDeltas));
 	}
 
-	/** @return a map containing ObjectType statistics. */
+	/**
+	 * Get a map containing ObjectType statistics.
+	 *
+	 * @return a map containing ObjectType statistics.
+	 */
 	public Map<Integer, ObjectType> getObjectTypes() {
 		HashMap<Integer, ObjectType> map = new HashMap<>();
 		map.put(Integer.valueOf(OBJ_BLOB), new ObjectType(