From 56cc6afeba265f224c52d32871b306418365b660 Mon Sep 17 00:00:00 2001 From: Matthias Sohn Date: Tue, 19 Dec 2017 00:16:02 +0100 Subject: [PATCH] Fix javadoc in org.eclipse.jgit storage/file and pack package Change-Id: If1fee165782823dc21d896073f60ee838365463d Signed-off-by: Matthias Sohn --- .../jgit/storage/file/FileBasedConfig.java | 27 ++++-- .../storage/file/FileRepositoryBuilder.java | 15 ++- .../jgit/storage/file/WindowCacheConfig.java | 53 +++++++++-- .../eclipse/jgit/storage/pack/PackConfig.java | 23 ++++- .../jgit/storage/pack/PackStatistics.java | 92 +++++++++++++++++-- 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 ba62418e1..32a8bfdbb 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} + *

* Load the configuration as a Git text style configuration file. *

* 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} + *

* Save the configuration as a Git text style configuration file. *

* Warning: 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 944fb4f5e..3e45bd5ce 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}. *

* 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 { /** + * {@inheritDoc} + *

* Create a repository matching the configuration in this builder. *

* 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 4205fc4e8..19fc63e00 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. Default is 128. */ @@ -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. Default is 10 MB. */ @@ -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. Default is 8 KB. */ @@ -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. - * Default false. + * 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. Default false. */ 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. * Default 10 MB. @@ -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 4f2374ff7..484cde29e 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 a811fe3cd..68cffd5b3 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 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 getObjectTypes() { HashMap map = new HashMap<>(); map.put(Integer.valueOf(OBJ_BLOB), new ObjectType(