From 8a6af368c4129ef35520ec72cc9f55a3f685bfb8 Mon Sep 17 00:00:00 2001 From: Matthias Sohn Date: Mon, 18 Dec 2017 16:52:40 +0100 Subject: [PATCH] Fix javadoc in org.eclipse.jgit lib package Change-Id: I1e85a951488177993521ce177fdea212615e6164 Signed-off-by: Matthias Sohn --- .../eclipse/jgit/lib/AbbreviatedObjectId.java | 36 ++- .../src/org/eclipse/jgit/lib/AnyObjectId.java | 50 ++-- .../jgit/lib/AsyncObjectLoaderQueue.java | 19 +- .../jgit/lib/AsyncObjectSizeQueue.java | 18 +- .../org/eclipse/jgit/lib/AsyncOperation.java | 4 +- .../jgit/lib/BaseRepositoryBuilder.java | 82 ++++-- .../org/eclipse/jgit/lib/BatchRefUpdate.java | 63 +++-- .../jgit/lib/BatchingProgressMonitor.java | 9 +- .../src/org/eclipse/jgit/lib/BitmapIndex.java | 6 +- .../org/eclipse/jgit/lib/BitmapObject.java | 2 +- .../org/eclipse/jgit/lib/BlobBasedConfig.java | 12 +- .../eclipse/jgit/lib/BlobObjectChecker.java | 2 +- .../org/eclipse/jgit/lib/BranchConfig.java | 15 +- .../jgit/lib/BranchTrackingStatus.java | 10 +- .../org/eclipse/jgit/lib/CheckoutEntry.java | 4 + .../org/eclipse/jgit/lib/CommitBuilder.java | 48 +++- .../src/org/eclipse/jgit/lib/Config.java | 50 ++-- .../src/org/eclipse/jgit/lib/ConfigLine.java | 1 + .../src/org/eclipse/jgit/lib/Constants.java | 10 +- .../src/org/eclipse/jgit/lib/CoreConfig.java | 10 + .../jgit/lib/DefaultTypedConfigGetter.java | 10 +- .../jgit/lib/EmptyProgressMonitor.java | 5 + .../src/org/eclipse/jgit/lib/FileMode.java | 22 +- .../src/org/eclipse/jgit/lib/IndexDiff.java | 51 +++- .../org/eclipse/jgit/lib/InflaterCache.java | 4 +- .../org/eclipse/jgit/lib/MutableObjectId.java | 21 +- .../eclipse/jgit/lib/NullProgressMonitor.java | 5 + .../org/eclipse/jgit/lib/ObjectChecker.java | 67 +++-- .../org/eclipse/jgit/lib/ObjectDatabase.java | 29 +- .../src/org/eclipse/jgit/lib/ObjectId.java | 6 + .../eclipse/jgit/lib/ObjectIdOwnerMap.java | 46 ++-- .../src/org/eclipse/jgit/lib/ObjectIdRef.java | 12 +- .../src/org/eclipse/jgit/lib/ObjectIdSet.java | 3 +- .../eclipse/jgit/lib/ObjectIdSubclassMap.java | 35 ++- .../org/eclipse/jgit/lib/ObjectInserter.java | 27 +- .../org/eclipse/jgit/lib/ObjectLoader.java | 48 ++-- .../org/eclipse/jgit/lib/ObjectReader.java | 72 ++--- .../org/eclipse/jgit/lib/ObjectStream.java | 16 +- .../src/org/eclipse/jgit/lib/PersonIdent.java | 50 +++- .../org/eclipse/jgit/lib/ProgressMonitor.java | 8 +- .../org/eclipse/jgit/lib/RebaseTodoFile.java | 7 +- .../org/eclipse/jgit/lib/RebaseTodoLine.java | 21 +- .../src/org/eclipse/jgit/lib/Ref.java | 14 +- .../org/eclipse/jgit/lib/RefComparator.java | 1 + .../src/org/eclipse/jgit/lib/RefDatabase.java | 73 ++--- .../src/org/eclipse/jgit/lib/RefRename.java | 25 +- .../src/org/eclipse/jgit/lib/RefUpdate.java | 87 ++++-- .../src/org/eclipse/jgit/lib/RefWriter.java | 33 ++- .../src/org/eclipse/jgit/lib/ReflogEntry.java | 15 +- .../org/eclipse/jgit/lib/ReflogReader.java | 14 +- .../src/org/eclipse/jgit/lib/Repository.java | 252 +++++++++++------- .../eclipse/jgit/lib/RepositoryBuilder.java | 2 +- .../org/eclipse/jgit/lib/RepositoryCache.java | 43 +-- .../jgit/lib/RepositoryCacheConfig.java | 23 +- .../org/eclipse/jgit/lib/RepositoryState.java | 4 +- .../org/eclipse/jgit/lib/StoredConfig.java | 11 +- .../src/org/eclipse/jgit/lib/SymbolicRef.java | 12 +- .../src/org/eclipse/jgit/lib/TagBuilder.java | 31 ++- .../eclipse/jgit/lib/TextProgressMonitor.java | 12 +- .../jgit/lib/ThreadSafeProgressMonitor.java | 18 +- .../org/eclipse/jgit/lib/TreeFormatter.java | 18 +- .../eclipse/jgit/lib/TypedConfigGetter.java | 22 +- .../src/org/eclipse/jgit/lib/UserConfig.java | 37 ++- .../eclipse/jgit/lib/internal/WorkQueue.java | 2 + 64 files changed, 1215 insertions(+), 550 deletions(-) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AbbreviatedObjectId.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AbbreviatedObjectId.java index 0567051a90..425f7f689a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AbbreviatedObjectId.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AbbreviatedObjectId.java @@ -52,7 +52,7 @@ import org.eclipse.jgit.util.NB; import org.eclipse.jgit.util.RawParseUtils; /** - * A prefix abbreviation of an {@link ObjectId}. + * A prefix abbreviation of an {@link org.eclipse.jgit.lib.ObjectId}. *

* Sometimes Git produces abbreviated SHA-1 strings, using sufficient leading * digits from the ObjectId name to still be unique within the repository the @@ -109,13 +109,14 @@ public final class AbbreviatedObjectId implements Serializable { } /** - * Convert an AbbreviatedObjectId from an {@link AnyObjectId}. + * Convert an AbbreviatedObjectId from an + * {@link org.eclipse.jgit.lib.AnyObjectId}. *

* This method copies over all bits of the Id, and is therefore complete * (see {@link #isComplete()}). * * @param id - * the {@link ObjectId} to convert from. + * the {@link org.eclipse.jgit.lib.ObjectId} to convert from. * @return the converted object id. */ public static final AbbreviatedObjectId fromObjectId(AnyObjectId id) { @@ -205,17 +206,29 @@ public final class AbbreviatedObjectId implements Serializable { w5 = new_5; } - /** @return number of hex digits appearing in this id */ + /** + * Get number of hex digits appearing in this id. + * + * @return number of hex digits appearing in this id. + */ public int length() { return nibbles; } - /** @return true if this ObjectId is actually a complete id. */ + /** + * Whether this ObjectId is actually a complete id. + * + * @return true if this ObjectId is actually a complete id. + */ public boolean isComplete() { return length() == Constants.OBJECT_ID_STRING_LENGTH; } - /** @return a complete ObjectId; null if {@link #isComplete()} is false */ + /** + * A complete ObjectId; null if {@link #isComplete()} is false + * + * @return a complete ObjectId; null if {@link #isComplete()} is false + */ public ObjectId toObjectId() { return isComplete() ? new ObjectId(w1, w2, w3, w4, w5) : null; } @@ -325,7 +338,11 @@ public final class AbbreviatedObjectId implements Serializable { return NB.compareUInt32(w5, mask(5, bs[p + 4])); } - /** @return value for a fan-out style map, only valid of length >= 2. */ + /** + * Get value for a fan-out style map, only valid of length >= 2. + * + * @return value for a fan-out style map, only valid of length >= 2. + */ public final int getFirstByte() { return w1 >>> 24; } @@ -334,11 +351,13 @@ public final class AbbreviatedObjectId implements Serializable { return mask(nibbles, word, v); } + /** {@inheritDoc} */ @Override public int hashCode() { return w1; } + /** {@inheritDoc} */ @Override public boolean equals(final Object o) { if (o instanceof AbbreviatedObjectId) { @@ -350,6 +369,8 @@ public final class AbbreviatedObjectId implements Serializable { } /** + * Get string form of the abbreviation, in lower case hexadecimal. + * * @return string form of the abbreviation, in lower case hexadecimal. */ public final String name() { @@ -375,6 +396,7 @@ public final class AbbreviatedObjectId implements Serializable { return new String(b, 0, nibbles); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AnyObjectId.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AnyObjectId.java index f964bf2b4f..58477657f6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AnyObjectId.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AnyObjectId.java @@ -53,9 +53,9 @@ import org.eclipse.jgit.util.NB; /** * A (possibly mutable) SHA-1 abstraction. *

- * If this is an instance of {@link MutableObjectId} the concept of equality - * with this instance can alter at any time, if this instance is modified to - * represent a different object name. + * If this is an instance of {@link org.eclipse.jgit.lib.MutableObjectId} the + * concept of equality with this instance can alter at any time, if this + * instance is modified to represent a different object name. */ public abstract class AnyObjectId implements Comparable { @@ -117,14 +117,16 @@ public abstract class AnyObjectId implements Comparable { * * @param index * index of the byte to obtain from the raw form of the ObjectId. - * Must be in range [0, {@link Constants#OBJECT_ID_LENGTH}). + * Must be in range [0, + * {@link org.eclipse.jgit.lib.Constants#OBJECT_ID_LENGTH}). * @return the value of the requested byte at {@code index}. Returned values * are unsigned and thus are in the range [0,255] rather than the * signed byte range of [-128, 127]. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * {@code index} is less than 0, equal to - * {@link Constants#OBJECT_ID_LENGTH}, or greater than - * {@link Constants#OBJECT_ID_LENGTH}. + * {@link org.eclipse.jgit.lib.Constants#OBJECT_ID_LENGTH}, or + * greater than + * {@link org.eclipse.jgit.lib.Constants#OBJECT_ID_LENGTH}. */ public final int getByte(int index) { int w; @@ -152,12 +154,9 @@ public abstract class AnyObjectId implements Comparable { } /** + * {@inheritDoc} + *

* Compare this ObjectId to another and obtain a sort ordering. - * - * @param other - * the other id to compare to. Must not be null. - * @return < 0 if this id comes before other; 0 if this id is equal to - * other; > 0 if this id comes after other. */ @Override public final int compareTo(final AnyObjectId other) { @@ -262,6 +261,7 @@ public abstract class AnyObjectId implements Comparable { return abbr.prefixCompare(this) == 0; } + /** {@inheritDoc} */ @Override public final int hashCode() { return w2; @@ -278,6 +278,7 @@ public abstract class AnyObjectId implements Comparable { return other != null ? equals(this, other) : false; } + /** {@inheritDoc} */ @Override public final boolean equals(final Object o) { if (o instanceof AnyObjectId) @@ -337,7 +338,7 @@ public abstract class AnyObjectId implements Comparable { * * @param w * the stream to write to. - * @throws IOException + * @throws java.io.IOException * the stream writing failed. */ public void copyRawTo(final OutputStream w) throws IOException { @@ -361,7 +362,7 @@ public abstract class AnyObjectId implements Comparable { * * @param w * the stream to copy to. - * @throws IOException + * @throws java.io.IOException * the stream writing failed. */ public void copyTo(final OutputStream w) throws IOException { @@ -422,7 +423,7 @@ public abstract class AnyObjectId implements Comparable { * * @param w * the stream to copy to. - * @throws IOException + * @throws java.io.IOException * the stream writing failed. */ public void copyTo(final Writer w) throws IOException { @@ -438,7 +439,7 @@ public abstract class AnyObjectId implements Comparable { * of object id (40 characters or larger). * @param w * the stream to copy to. - * @throws IOException + * @throws java.io.IOException * the stream writing failed. */ public void copyTo(final char[] tmp, final Writer w) throws IOException { @@ -488,6 +489,7 @@ public abstract class AnyObjectId implements Comparable { dst[o--] = '0'; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { @@ -495,6 +497,8 @@ public abstract class AnyObjectId implements Comparable { } /** + *

name.

+ * * @return string form of the SHA-1, in lower case hexadecimal. */ public final String name() { @@ -502,6 +506,8 @@ public abstract class AnyObjectId implements Comparable { } /** + * Get string form of the SHA-1, in lower case hexadecimal. + * * @return string form of the SHA-1, in lower case hexadecimal. */ public final String getName() { @@ -511,9 +517,11 @@ public abstract class AnyObjectId implements Comparable { /** * Return an abbreviation (prefix) of this object SHA-1. *

- * This implementation does not guarantee uniqueness. Callers should - * instead use {@link ObjectReader#abbreviate(AnyObjectId, int)} to obtain a - * unique abbreviation within the scope of a particular object database. + * This implementation does not guarantee uniqueness. Callers should instead + * use + * {@link org.eclipse.jgit.lib.ObjectReader#abbreviate(AnyObjectId, int)} to + * obtain a unique abbreviation within the scope of a particular object + * database. * * @param len * length of the abbreviated string. @@ -532,8 +540,8 @@ public abstract class AnyObjectId implements Comparable { * Obtain an immutable copy of this current object name value. *

* Only returns this if this instance is an unsubclassed - * instance of {@link ObjectId}; otherwise a new instance is returned - * holding the same value. + * instance of {@link org.eclipse.jgit.lib.ObjectId}; otherwise a new + * instance is returned holding the same value. *

* This method is useful to shed any additional memory that may be tied to * the subclass, yet retain the unique identity of the object id for future diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectLoaderQueue.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectLoaderQueue.java index a3732eaacd..b4ea0e907f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectLoaderQueue.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectLoaderQueue.java @@ -63,30 +63,37 @@ public interface AsyncObjectLoaderQueue extends * Position this queue onto the next available result. * * Even if this method returns true, {@link #open()} may still throw - * {@link MissingObjectException} if the underlying object database was - * concurrently modified and the current object is no longer available. + * {@link org.eclipse.jgit.errors.MissingObjectException} if the underlying + * object database was concurrently modified and the current object is no + * longer available. * * @return true if there is a result available; false if the queue has * finished its input iteration. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. If the implementation is retaining * the application's objects {@link #getCurrent()} will be the * current object that is missing. There may be more results * still available, so the caller should continue invoking next * to examine another result. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public boolean next() throws MissingObjectException, IOException; /** + * Get the current object, null if the implementation lost track. + * * @return the current object, null if the implementation lost track. * Implementations may for performance reasons discard the caller's * ObjectId and provider their own through {@link #getObjectId()}. */ public T getCurrent(); - /** @return the ObjectId of the current object. Never null. */ + /** + * Get the ObjectId of the current object. Never null. + * + * @return the ObjectId of the current object. Never null. + */ public ObjectId getObjectId(); /** @@ -105,7 +112,7 @@ public interface AsyncObjectLoaderQueue extends * current object that is missing. There may be more results * still available, so the caller should continue invoking next * to examine another result. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public ObjectLoader open() throws IOException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectSizeQueue.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectSizeQueue.java index c9667242a4..03efcd295e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectSizeQueue.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectSizeQueue.java @@ -64,27 +64,37 @@ public interface AsyncObjectSizeQueue extends * * @return true if there is a result available; false if the queue has * finished its input iteration. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. If the implementation is retaining * the application's objects {@link #getCurrent()} will be the * current object that is missing. There may be more results * still available, so the caller should continue invoking next * to examine another result. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public boolean next() throws MissingObjectException, IOException; /** + *

getCurrent.

+ * * @return the current object, null if the implementation lost track. * Implementations may for performance reasons discard the caller's * ObjectId and provider their own through {@link #getObjectId()}. */ public T getCurrent(); - /** @return the ObjectId of the current object. Never null. */ + /** + * Get the ObjectId of the current object. Never null. + * + * @return the ObjectId of the current object. Never null. + */ public ObjectId getObjectId(); - /** @return the size of the current object. */ + /** + * Get the size of the current object. + * + * @return the size of the current object. + */ public long getSize(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncOperation.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncOperation.java index fb73dc1c5d..00555b0907 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncOperation.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncOperation.java @@ -70,6 +70,8 @@ public interface AsyncOperation { */ public boolean cancel(boolean mayInterruptIfRunning); - /** Release resources used by the operation, including cancellation. */ + /** + * Release resources used by the operation, including cancellation. + */ public void release(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BaseRepositoryBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BaseRepositoryBuilder.java index 825c1f704a..2c7c6cb060 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BaseRepositoryBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BaseRepositoryBuilder.java @@ -160,7 +160,11 @@ public class BaseRepositoryBuilder alts = alternateObjectDirectories; if (alts == null) @@ -285,7 +301,11 @@ public class BaseRepositoryBuilder * Describes the default for commands in this batch that do not override it - * with {@link ReceiveCommand#setRefLogMessage(String, boolean)}. + * with + * {@link org.eclipse.jgit.transport.ReceiveCommand#setRefLogMessage(String, boolean)}. * * @return true if the message should include the result. */ @@ -204,21 +212,23 @@ public class BatchRefUpdate { /** * Set the message to include in the reflog. *

- * Repository implementations may limit which reflogs are written by default, - * based on the project configuration. If a repo is not configured to write - * logs for this ref by default, setting the message alone may have no effect. - * To indicate that the repo should write logs for this update in spite of - * configured defaults, use {@link #setForceRefLog(boolean)}. + * Repository implementations may limit which reflogs are written by + * default, based on the project configuration. If a repo is not configured + * to write logs for this ref by default, setting the message alone may have + * no effect. To indicate that the repo should write logs for this update in + * spite of configured defaults, use {@link #setForceRefLog(boolean)}. *

* Describes the default for commands in this batch that do not override it - * with {@link ReceiveCommand#setRefLogMessage(String, boolean)}. + * with + * {@link org.eclipse.jgit.transport.ReceiveCommand#setRefLogMessage(String, boolean)}. * * @param msg - * the message to describe this change. If null and appendStatus is - * false, the reflog will not be updated. + * the message to describe this change. If null and appendStatus + * is false, the reflog will not be updated. * @param appendStatus * true if the status of the ref change (fast-forward or - * forced-update) should be appended to the user supplied message. + * forced-update) should be appended to the user supplied + * message. * @return {@code this}. */ public BatchRefUpdate setRefLogMessage(String msg, boolean appendStatus) { @@ -286,12 +296,15 @@ public class BatchRefUpdate { * {@code REJECTED_OTHER_REASON}. *

* This method only works if the underlying ref database supports atomic - * transactions, i.e. {@link RefDatabase#performsAtomicTransactions()} returns - * true. Calling this method with true if the underlying ref database does not - * support atomic transactions will cause all commands to fail with {@code + * transactions, i.e. + * {@link org.eclipse.jgit.lib.RefDatabase#performsAtomicTransactions()} + * returns true. Calling this method with true if the underlying ref + * database does not support atomic transactions will cause all commands to + * fail with {@code * REJECTED_OTHER_REASON}. * - * @param atomic whether updates should be atomic. + * @param atomic + * whether updates should be atomic. * @return {@code this} * @since 4.4 */ @@ -301,6 +314,8 @@ public class BatchRefUpdate { } /** + * Whether updates should be atomic. + * * @return atomic whether updates should be atomic. * @since 4.4 */ @@ -335,7 +350,11 @@ public class BatchRefUpdate { return pushCert; } - /** @return commands this update will process. */ + /** + * Get commands this update will process. + * + * @return commands this update will process. + */ public List getCommands() { return Collections.unmodifiableList(commands); } @@ -401,6 +420,8 @@ public class BatchRefUpdate { } /** + * Get list of timestamps the batch must wait for. + * * @return list of timestamps the batch must wait for. * @since 4.6 */ @@ -415,6 +436,7 @@ public class BatchRefUpdate { * Request the batch to wait for the affected timestamps to resolve. * * @param ts + * a {@link org.eclipse.jgit.util.time.ProposedTimestamp} object. * @return {@code this}. * @since 4.6 */ @@ -434,7 +456,7 @@ public class BatchRefUpdate { *

* Implementations must respect the atomicity requirements of the underlying * database as described in {@link #setAtomic(boolean)} and - * {@link RefDatabase#performsAtomicTransactions()}. + * {@link org.eclipse.jgit.lib.RefDatabase#performsAtomicTransactions()}. * * @param walk * a RevWalk to parse tags in case the storage system wants to @@ -443,7 +465,7 @@ public class BatchRefUpdate { * progress monitor to receive update status on. * @param options * a list of option strings; set null to execute without - * @throws IOException + * @throws java.io.IOException * the database is unable to accept the update. Individual * command status must be tested to determine if there is a * partial failure, or a total failure. @@ -601,7 +623,7 @@ public class BatchRefUpdate { * store them pre-peeled, a common performance optimization. * @param monitor * progress monitor to receive update status on. - * @throws IOException + * @throws java.io.IOException * the database is unable to accept the update. Individual * command status must be tested to determine if there is a * partial failure, or a total failure. @@ -658,7 +680,7 @@ public class BatchRefUpdate { * @param cmd * specific command the update should be created to copy. * @return a single reference update command. - * @throws IOException + * @throws java.io.IOException * the reference database cannot make a new update object for * the given reference. */ @@ -746,6 +768,7 @@ public class BatchRefUpdate { : isForceRefLog(); } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchingProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchingProgressMonitor.java index a75293d6cb..4eb7b7fb78 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchingProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchingProgressMonitor.java @@ -48,7 +48,9 @@ import java.util.concurrent.TimeUnit; import org.eclipse.jgit.lib.internal.WorkQueue; -/** ProgressMonitor that batches update events. */ +/** + * ProgressMonitor that batches update events. + */ public abstract class BatchingProgressMonitor implements ProgressMonitor { private long delayStartTime; @@ -70,11 +72,13 @@ public abstract class BatchingProgressMonitor implements ProgressMonitor { delayStartUnit = unit; } + /** {@inheritDoc} */ @Override public void start(int totalTasks) { // Ignore the number of tasks. } + /** {@inheritDoc} */ @Override public void beginTask(String title, int work) { endTask(); @@ -83,12 +87,14 @@ public abstract class BatchingProgressMonitor implements ProgressMonitor { task.delay(delayStartTime, delayStartUnit); } + /** {@inheritDoc} */ @Override public void update(int completed) { if (task != null) task.update(this, completed); } + /** {@inheritDoc} */ @Override public void endTask() { if (task != null) { @@ -97,6 +103,7 @@ public abstract class BatchingProgressMonitor implements ProgressMonitor { } } + /** {@inheritDoc} */ @Override public boolean isCancelled() { return false; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapIndex.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapIndex.java index 00f42a49a5..fc354db113 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapIndex.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapIndex.java @@ -63,7 +63,11 @@ public interface BitmapIndex { */ Bitmap getBitmap(AnyObjectId objectId); - /** @return a new {@code BitmapBuilder} based on the values in the index. */ + /** + * Create a new {@code BitmapBuilder} based on the values in the index. + * + * @return a new {@code BitmapBuilder} based on the values in the index. + */ BitmapBuilder newBitmapBuilder(); /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapObject.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapObject.java index 4e0dc2cda1..f2917dc888 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapObject.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapObject.java @@ -50,7 +50,7 @@ package org.eclipse.jgit.lib; */ public abstract class BitmapObject { /** - * Get Git object type. See {@link Constants}. + * Get Git object type. See {@link org.eclipse.jgit.lib.Constants}. * * @return object type */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobBasedConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobBasedConfig.java index 8958ce7e85..3ff92dc739 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobBasedConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobBasedConfig.java @@ -73,7 +73,7 @@ public class BlobBasedConfig extends Config { * the base configuration file * @param blob * the byte array, should be UTF-8 encoded text. - * @throws ConfigInvalidException + * @throws org.eclipse.jgit.errors.ConfigInvalidException * the byte array is not a valid configuration format. */ public BlobBasedConfig(Config base, final byte[] blob) @@ -98,9 +98,9 @@ public class BlobBasedConfig extends Config { * the repository * @param objectId * the object identifier - * @throws IOException + * @throws java.io.IOException * the blob cannot be read from the repository. - * @throws ConfigInvalidException + * @throws org.eclipse.jgit.errors.ConfigInvalidException * the blob is not a valid configuration format. */ public BlobBasedConfig(Config base, Repository db, AnyObjectId objectId) @@ -134,11 +134,11 @@ public class BlobBasedConfig extends Config { * the tree (or commit) that contains the object * @param path * the path within the tree - * @throws FileNotFoundException + * @throws java.io.FileNotFoundException * the path does not exist in the commit's tree. - * @throws IOException + * @throws java.io.IOException * the tree and/or blob cannot be accessed. - * @throws ConfigInvalidException + * @throws org.eclipse.jgit.errors.ConfigInvalidException * the blob is not a valid configuration format. */ public BlobBasedConfig(Config base, Repository db, AnyObjectId treeish, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobObjectChecker.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobObjectChecker.java index 0fe63ae5b4..3fa3168327 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobObjectChecker.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobObjectChecker.java @@ -85,7 +85,7 @@ public interface BlobObjectChecker { * * @param id * identity of the object being checked. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. */ void endBlob(AnyObjectId id) throws CorruptObjectException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchConfig.java index f1b7fb2172..6b8553cdfa 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchConfig.java @@ -113,6 +113,8 @@ public class BranchConfig { } /** + * Get the full tracking branch name + * * @return the full tracking branch name or null if it could * not be determined */ @@ -129,6 +131,8 @@ public class BranchConfig { } /** + * Get the full remote-tracking branch name + * * @return the full remote-tracking branch name or {@code null} if it could * not be determined. If you also want local tracked branches use * {@link #getTrackingBranch()} instead. @@ -143,6 +147,9 @@ public class BranchConfig { } /** + * Whether the "remote" setting points to the local repository (with + * {@value #LOCAL_REPOSITORY}) + * * @return {@code true} if the "remote" setting points to the local * repository (with {@value #LOCAL_REPOSITORY}), false otherwise * @since 3.5 @@ -152,6 +159,8 @@ public class BranchConfig { } /** + * Get the remote this branch is configured to fetch from/push to> + * * @return the remote this branch is configured to fetch from/push to, or * {@code null} if not defined * @since 3.5 @@ -162,6 +171,8 @@ public class BranchConfig { } /** + * Get the name of the upstream branch as it is called on the remote + * * @return the name of the upstream branch as it is called on the remote, or * {@code null} if not defined * @since 3.5 @@ -172,6 +183,8 @@ public class BranchConfig { } /** + * Whether the branch is configured to be rebased + * * @return {@code true} if the branch is configured to be rebased * @since 3.5 */ @@ -182,7 +195,7 @@ public class BranchConfig { /** * Retrieves the config value of branch.[name].rebase. * - * @return the {@link BranchRebaseMode} + * @return the {@link org.eclipse.jgit.lib.BranchConfig.BranchRebaseMode} * @since 4.5 */ public BranchRebaseMode getRebaseMode() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchTrackingStatus.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchTrackingStatus.java index d4fccf9070..ac1529f990 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchTrackingStatus.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchTrackingStatus.java @@ -65,7 +65,7 @@ public class BranchTrackingStatus { * @param branchName * the local branch * @return the tracking status, or null if it is not known - * @throws IOException + * @throws java.io.IOException */ public static BranchTrackingStatus of(Repository repository, String branchName) throws IOException { @@ -119,6 +119,8 @@ public class BranchTrackingStatus { } /** + * Get full remote-tracking branch name + * * @return full remote-tracking branch name */ public String getRemoteTrackingBranch() { @@ -126,6 +128,9 @@ public class BranchTrackingStatus { } /** + * Get number of commits that the local branch is ahead of the + * remote-tracking branch + * * @return number of commits that the local branch is ahead of the * remote-tracking branch */ @@ -134,6 +139,9 @@ public class BranchTrackingStatus { } /** + * Get number of commits that the local branch is behind of the + * remote-tracking branch + * * @return number of commits that the local branch is behind of the * remote-tracking branch */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/CheckoutEntry.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/CheckoutEntry.java index 34d0b14adf..cfc0cc86d1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/CheckoutEntry.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/CheckoutEntry.java @@ -8,11 +8,15 @@ package org.eclipse.jgit.lib; public interface CheckoutEntry { /** + * Get the name of the branch before checkout + * * @return the name of the branch before checkout */ public abstract String getFromBranch(); /** + * Get the name of the branch after checkout + * * @return the name of the branch after checkout */ public abstract String getToBranch(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/CommitBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/CommitBuilder.java index c5c488dac3..2217fde049 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/CommitBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/CommitBuilder.java @@ -88,13 +88,19 @@ public class CommitBuilder { private Charset encoding; - /** Initialize an empty commit. */ + /** + * Initialize an empty commit. + */ public CommitBuilder() { parentIds = EMPTY_OBJECTID_LIST; encoding = Constants.CHARSET; } - /** @return id of the root tree listing this commit's snapshot. */ + /** + * Get id of the root tree listing this commit's snapshot. + * + * @return id of the root tree listing this commit's snapshot. + */ public ObjectId getTreeId() { return treeId; } @@ -109,7 +115,11 @@ public class CommitBuilder { treeId = id.copy(); } - /** @return the author of this commit (who wrote it). */ + /** + * Get the author of this commit (who wrote it). + * + * @return the author of this commit (who wrote it). + */ public PersonIdent getAuthor() { return author; } @@ -124,7 +134,11 @@ public class CommitBuilder { author = newAuthor; } - /** @return the committer and commit time for this object. */ + /** + * Get the committer and commit time for this object. + * + * @return the committer and commit time for this object. + */ public PersonIdent getCommitter() { return committer; } @@ -139,7 +153,11 @@ public class CommitBuilder { committer = newCommitter; } - /** @return the ancestors of this commit. Never null. */ + /** + * Get the ancestors of this commit. + * + * @return the ancestors of this commit. Never null. + */ public ObjectId[] getParentIds() { return parentIds; } @@ -210,7 +228,11 @@ public class CommitBuilder { } } - /** @return the complete commit message. */ + /** + * Get the complete commit message. + * + * @return the complete commit message. + */ public String getMessage() { return message; } @@ -229,7 +251,8 @@ public class CommitBuilder { * Set the encoding for the commit information * * @param encodingName - * the encoding name. See {@link Charset#forName(String)}. + * the encoding name. See + * {@link java.nio.charset.Charset#forName(String)}. */ public void setEncoding(String encodingName) { encoding = Charset.forName(encodingName); @@ -245,7 +268,11 @@ public class CommitBuilder { encoding = enc; } - /** @return the encoding that should be used for the commit message text. */ + /** + * Get the encoding that should be used for the commit message text. + * + * @return the encoding that should be used for the commit message text. + */ public Charset getEncoding() { return encoding; } @@ -255,7 +282,7 @@ public class CommitBuilder { * * @return this object in the canonical commit format, suitable for storage * in a repository. - * @throws UnsupportedEncodingException + * @throws java.io.UnsupportedEncodingException * the encoding specified by {@link #getEncoding()} is not * supported by this Java runtime. */ @@ -314,7 +341,7 @@ public class CommitBuilder { * * @return this object in the canonical commit format, suitable for storage * in a repository. - * @throws UnsupportedEncodingException + * @throws java.io.UnsupportedEncodingException * the encoding specified by {@link #getEncoding()} is not * supported by this Java runtime. */ @@ -322,6 +349,7 @@ public class CommitBuilder { return build(); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Config.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Config.java index b98586cfd4..39161214de 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Config.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Config.java @@ -108,7 +108,9 @@ public class Config { */ static final String MAGIC_EMPTY_VALUE = new String(); - /** Create a configuration with no default fallback. */ + /** + * Create a configuration with no default fallback. + */ public Config() { this(null); } @@ -126,8 +128,8 @@ public class Config { } /** - * Globally sets a {@link TypedConfigGetter} that is subsequently used to - * read typed values from all git configs. + * Globally sets a {@link org.eclipse.jgit.lib.TypedConfigGetter} that is + * subsequently used to read typed values from all git configs. * * @param getter * to use; if {@code null} use the default getter. @@ -340,8 +342,6 @@ public class Config { /** * Parse an enumeration from the configuration. * - * @param - * type of the enumeration object. * @param section * section the key is grouped within. * @param subsection @@ -374,8 +374,6 @@ public class Config { /** * Parse an enumeration from the configuration. * - * @param - * type of the enumeration object. * @param all * all possible values in the enumeration which should be * recognized. Typically {@code EnumType.values()}. @@ -471,7 +469,8 @@ public class Config { } /** - * Parse a list of {@link RefSpec}s from the configuration. + * Parse a list of {@link org.eclipse.jgit.transport.RefSpec}s from the + * configuration. * * @param section * section the key is in. @@ -479,7 +478,8 @@ public class Config { * subsection the key is in, or null if not in a subsection. * @param name * the key name. - * @return a possibly empty list of {@link RefSpec}s + * @return a possibly empty list of + * {@link org.eclipse.jgit.transport.RefSpec}s * @since 4.9 */ public List getRefSpecs(String section, String subsection, @@ -488,6 +488,9 @@ public class Config { } /** + * Get set of all subsections of specified section within this configuration + * and its base configuration + * * @param section * section to search for. * @return set of all subsections of specified section within this @@ -501,16 +504,20 @@ public class Config { } /** - * @return the sections defined in this {@link Config}. The set's iterator - * returns sections in the order they are declared by the - * configuration starting from this instance and progressing through - * the base. + * Get the sections defined in this {@link org.eclipse.jgit.lib.Config}. + * + * @return the sections defined in this {@link org.eclipse.jgit.lib.Config}. + * The set's iterator returns sections in the order they are + * declared by the configuration starting from this instance and + * progressing through the base. */ public Set getSections() { return getState().getSections(); } /** + * Get the list of names defined for this section + * * @param section * the section * @return the list of names defined for this section @@ -520,6 +527,8 @@ public class Config { } /** + * Get the list of names defined for this subsection + * * @param section * the section * @param subsection @@ -531,6 +540,8 @@ public class Config { } /** + * Get the list of names defined for this section + * * @param section * the section * @param recursive @@ -544,6 +555,8 @@ public class Config { } /** + * Get the list of names defined for this section + * * @param section * the section * @param subsection @@ -600,7 +613,8 @@ public class Config { * Adds a listener to be notified about changes. *

* Clients are supposed to remove the listeners after they are done with - * them using the {@link ListenerHandle#remove()} method + * them using the {@link org.eclipse.jgit.events.ListenerHandle#remove()} + * method * * @param listener * the listener @@ -755,8 +769,6 @@ public class Config { * name = value * * - * @param - * type of the enumeration object. * @param section * section name, e.g "branch" * @param subsection @@ -976,6 +988,8 @@ public class Config { } /** + * Get this configuration, formatted as a Git style text file. + * * @return this configuration, formatted as a Git style text file. */ public String toText() { @@ -1025,7 +1039,7 @@ public class Config { * * @param text * Git style text file listing configuration properties. - * @throws ConfigInvalidException + * @throws org.eclipse.jgit.errors.ConfigInvalidException * the text supplied is not formatted correctly. No changes were * made to {@code this}. */ @@ -1114,7 +1128,7 @@ public class Config { * possibly relative path to the included config, as specified in * this config * @return the read bytes, or null if the included config should be ignored - * @throws ConfigInvalidException + * @throws org.eclipse.jgit.errors.ConfigInvalidException * if something went wrong while reading the config * @since 4.10 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ConfigLine.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ConfigLine.java index 8a49bdb4f3..d5f1d8f085 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ConfigLine.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ConfigLine.java @@ -112,6 +112,7 @@ class ConfigLine { return a.equals(b); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Constants.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Constants.java index bb7316dc5f..d2160011be 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Constants.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Constants.java @@ -55,7 +55,9 @@ import org.eclipse.jgit.errors.CorruptObjectException; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.util.MutableInteger; -/** Misc. constants used throughout JGit. */ +/** + * Misc. constants used throughout JGit. + */ @SuppressWarnings("nls") public final class Constants { /** Hash function used natively by Git for all objects. */ @@ -446,7 +448,7 @@ public final class Constants { * Create a new digest function for objects. * * @return a new digest object. - * @throws RuntimeException + * @throws java.lang.RuntimeException * this Java virtual machine does not support the required hash * function. Very unlikely given that JGit uses a hash function * that is in the Java reference specification. @@ -524,7 +526,7 @@ public final class Constants { * endMark when the parse is successful. * @return a type code constant (one of {@link #OBJ_BLOB}, * {@link #OBJ_COMMIT}, {@link #OBJ_TAG}, {@link #OBJ_TREE}. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * there is no valid type identified by typeString. */ public static int decodeTypeString(final AnyObjectId id, @@ -602,7 +604,7 @@ public final class Constants { * 127 (outside of 7-bit ASCII). * @return a byte array of the same length as the input string, holding the * same characters, in the same order. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the input string contains one or more characters outside of * the 7-bit ASCII character space. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/CoreConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/CoreConfig.java index fdbbe39393..32a894f795 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/CoreConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/CoreConfig.java @@ -180,6 +180,8 @@ public class CoreConfig { } /** + * Get the compression level to use when storing loose objects + * * @return The compression level to use when storing loose objects */ public int getCompression() { @@ -187,6 +189,8 @@ public class CoreConfig { } /** + * Get the preferred pack index file format; 0 for oldest possible. + * * @return the preferred pack index file format; 0 for oldest possible. */ public int getPackIndexVersion() { @@ -194,6 +198,8 @@ public class CoreConfig { } /** + * Whether to log all refUpdates + * * @return whether to log all refUpdates */ public boolean isLogAllRefUpdates() { @@ -201,6 +207,8 @@ public class CoreConfig { } /** + * Get path of excludesfile + * * @return path of excludesfile */ public String getExcludesFile() { @@ -208,6 +216,8 @@ public class CoreConfig { } /** + * Get path of attributesfile + * * @return path of attributesfile * @since 3.7 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/DefaultTypedConfigGetter.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/DefaultTypedConfigGetter.java index fd37747601..68f881dd1e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/DefaultTypedConfigGetter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/DefaultTypedConfigGetter.java @@ -57,13 +57,14 @@ import org.eclipse.jgit.transport.RefSpec; import org.eclipse.jgit.util.StringUtils; /** - * An {@link TypedConfigGetter} that throws {@link IllegalArgumentException} on - * invalid values. + * An {@link org.eclipse.jgit.lib.TypedConfigGetter} that throws + * {@link java.lang.IllegalArgumentException} on invalid values. * * @since 4.9 */ public class DefaultTypedConfigGetter implements TypedConfigGetter { + /** {@inheritDoc} */ @Override public boolean getBoolean(Config config, String section, String subsection, String name, boolean defaultValue) { @@ -82,6 +83,7 @@ public class DefaultTypedConfigGetter implements TypedConfigGetter { } } + /** {@inheritDoc} */ @Override public > T getEnum(Config config, T[] all, String section, String subsection, String name, T defaultValue) { @@ -139,6 +141,7 @@ public class DefaultTypedConfigGetter implements TypedConfigGetter { } } + /** {@inheritDoc} */ @Override public int getInt(Config config, String section, String subsection, String name, int defaultValue) { @@ -150,6 +153,7 @@ public class DefaultTypedConfigGetter implements TypedConfigGetter { .format(JGitText.get().integerValueOutOfRange, section, name)); } + /** {@inheritDoc} */ @Override public long getLong(Config config, String section, String subsection, String name, long defaultValue) { @@ -187,6 +191,7 @@ public class DefaultTypedConfigGetter implements TypedConfigGetter { } } + /** {@inheritDoc} */ @Override public long getTimeUnit(Config config, String section, String subsection, String name, long defaultValue, TimeUnit wantUnit) { @@ -286,6 +291,7 @@ public class DefaultTypedConfigGetter implements TypedConfigGetter { section, name, valueString)); } + /** {@inheritDoc} */ @Override public @NonNull List getRefSpecs(Config config, String section, String subsection, String name) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/EmptyProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/EmptyProgressMonitor.java index c236c35f3c..8ae90c6652 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/EmptyProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/EmptyProgressMonitor.java @@ -51,26 +51,31 @@ package org.eclipse.jgit.lib; */ public abstract class EmptyProgressMonitor implements ProgressMonitor { + /** {@inheritDoc} */ @Override public void start(int totalTasks) { // empty } + /** {@inheritDoc} */ @Override public void beginTask(String title, int totalWork) { // empty } + /** {@inheritDoc} */ @Override public void update(int completed) { // empty } + /** {@inheritDoc} */ @Override public void endTask() { // empty } + /** {@inheritDoc} */ @Override public boolean isCancelled() { return false; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/FileMode.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/FileMode.java index edbc709f48..7852371648 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/FileMode.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/FileMode.java @@ -82,7 +82,9 @@ public abstract class FileMode { /** Bit pattern for {@link #TYPE_MASK} matching {@link #MISSING}. */ public static final int TYPE_MISSING = 0000000; - /** Mode indicating an entry is a tree (aka directory). */ + /** + * Mode indicating an entry is a tree (aka directory). + */ public static final FileMode TREE = new FileMode(TYPE_TREE, Constants.OBJ_TREE) { @Override @@ -197,9 +199,11 @@ public abstract class FileMode { } /** - * Test a file mode for equality with this {@link FileMode} object. + * Test a file mode for equality with this + * {@link org.eclipse.jgit.lib.FileMode} object. * * @param modebits + * a int. * @return true if the mode bits represent the same mode as this object */ public abstract boolean equals(final int modebits); @@ -215,7 +219,7 @@ public abstract class FileMode { * * @param os * stream to copy the mode to. - * @throws IOException + * @throws java.io.IOException * the stream encountered an error during the copy. */ public void copyTo(final OutputStream os) throws IOException { @@ -240,6 +244,8 @@ public abstract class FileMode { } /** + * Copy the number of bytes written by {@link #copyTo(OutputStream)}. + * * @return the number of bytes written by {@link #copyTo(OutputStream)}. */ public int copyToLength() { @@ -249,7 +255,7 @@ public abstract class FileMode { /** * Get the object type that should appear for this type of mode. *

- * See the object type constants in {@link Constants}. + * See the object type constants in {@link org.eclipse.jgit.lib.Constants}. * * @return one of the well known object type constants. */ @@ -257,13 +263,19 @@ public abstract class FileMode { return objectType; } - /** Format this mode as an octal string (for debugging only). */ + /** + * {@inheritDoc} + *

+ * Format this mode as an octal string (for debugging only). + */ @Override public String toString() { return Integer.toOctalString(modeBits); } /** + * Get the mode bits as an integer. + * * @return The mode bits as an integer. */ public int getBits() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/IndexDiff.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/IndexDiff.java index ea573a48d7..b3158df142 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/IndexDiff.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/IndexDiff.java @@ -285,12 +285,13 @@ public class IndexDiff { * Construct an IndexDiff * * @param repository + * a {@link org.eclipse.jgit.lib.Repository} object. * @param revstr - * symbolic name e.g. HEAD - * An EmptyTreeIterator is used if revstr cannot be resolved. + * symbolic name e.g. HEAD An EmptyTreeIterator is used if + * revstr cannot be resolved. * @param workingTreeIterator * iterator for working directory - * @throws IOException + * @throws java.io.IOException */ public IndexDiff(Repository repository, String revstr, WorkingTreeIterator workingTreeIterator) throws IOException { @@ -301,11 +302,12 @@ public class IndexDiff { * Construct an Indexdiff * * @param repository + * a {@link org.eclipse.jgit.lib.Repository} object. * @param objectId * tree id. If null, an EmptyTreeIterator is used. * @param workingTreeIterator * iterator for working directory - * @throws IOException + * @throws java.io.IOException */ public IndexDiff(Repository repository, ObjectId objectId, WorkingTreeIterator workingTreeIterator) throws IOException { @@ -321,6 +323,8 @@ public class IndexDiff { } /** + * Defines how modifications in submodules are treated + * * @param mode * defines how modifications in submodules are treated * @since 3.6 @@ -336,7 +340,8 @@ public class IndexDiff { public interface WorkingTreeIteratorFactory { /** * @param repo - * @return a WorkingTreeIterator for repo + * the repository + * @return working tree iterator */ public WorkingTreeIterator getWorkingTreeIterator(Repository repo); } @@ -363,6 +368,7 @@ public class IndexDiff { * files. * * @param filter + * a {@link org.eclipse.jgit.treewalk.filter.TreeFilter} object. */ public void setFilter(TreeFilter filter) { this.filter = filter; @@ -374,7 +380,7 @@ public class IndexDiff { * monitor is required. * * @return if anything is different between index, tree, and workdir - * @throws IOException + * @throws java.io.IOException */ public boolean diff() throws IOException { return diff(null, 0, 0, ""); //$NON-NLS-1$ @@ -396,10 +402,9 @@ public class IndexDiff { * number or estimated files in the working tree * @param estIndexSize * number of estimated entries in the cache - * @param title - * + * @param title a {@link java.lang.String} object. * @return if anything is different between index, tree, and workdir - * @throws IOException + * @throws java.io.IOException */ public boolean diff(final ProgressMonitor monitor, int estWorkTreeSize, int estIndexSize, final String title) @@ -621,6 +626,8 @@ public class IndexDiff { } /** + * Get list of files added to the index, not in the tree + * * @return list of files added to the index, not in the tree */ public Set getAdded() { @@ -628,6 +635,8 @@ public class IndexDiff { } /** + * Get list of files changed from tree to index + * * @return list of files changed from tree to index */ public Set getChanged() { @@ -635,6 +644,8 @@ public class IndexDiff { } /** + * Get list of files removed from index, but in tree + * * @return list of files removed from index, but in tree */ public Set getRemoved() { @@ -642,6 +653,8 @@ public class IndexDiff { } /** + * Get list of files in index, but not filesystem + * * @return list of files in index, but not filesystem */ public Set getMissing() { @@ -649,6 +662,8 @@ public class IndexDiff { } /** + * Get list of files modified on disk relative to the index + * * @return list of files modified on disk relative to the index */ public Set getModified() { @@ -656,6 +671,8 @@ public class IndexDiff { } /** + * Get list of files that are not ignored, and not in the index. + * * @return list of files that are not ignored, and not in the index. */ public Set getUntracked() { @@ -663,6 +680,9 @@ public class IndexDiff { } /** + * Get list of files that are in conflict, corresponds to the keys of + * {@link #getConflictingStageStates()} + * * @return list of files that are in conflict, corresponds to the keys of * {@link #getConflictingStageStates()} */ @@ -671,8 +691,11 @@ public class IndexDiff { } /** + * Get the map from each path of {@link #getConflicting()} to its + * corresponding {@link org.eclipse.jgit.lib.IndexDiff.StageState} + * * @return the map from each path of {@link #getConflicting()} to its - * corresponding {@link StageState} + * corresponding {@link org.eclipse.jgit.lib.IndexDiff.StageState} * @since 3.0 */ public Map getConflictingStageStates() { @@ -693,6 +716,8 @@ public class IndexDiff { } /** + * Get list of files with the flag assume-unchanged + * * @return list of files with the flag assume-unchanged */ public Set getAssumeUnchanged() { @@ -707,6 +732,8 @@ public class IndexDiff { } /** + * Get list of folders containing only untracked files/folders + * * @return list of folders containing only untracked files/folders */ public Set getUntrackedFolders() { @@ -717,7 +744,7 @@ public class IndexDiff { /** * Get the file mode of the given path in the index * - * @param path + * @param path a {@link java.lang.String} object. * @return file mode */ public FileMode getIndexMode(final String path) { @@ -729,7 +756,7 @@ public class IndexDiff { * Get the list of paths that IndexDiff has detected to differ and have the * given file mode * - * @param mode + * @param mode a {@link org.eclipse.jgit.lib.FileMode} object. * @return the list of paths that IndexDiff has detected to differ and have * the given file mode * @since 3.6 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/InflaterCache.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/InflaterCache.java index f9517a0a2e..a97721c732 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/InflaterCache.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/InflaterCache.java @@ -46,7 +46,9 @@ package org.eclipse.jgit.lib; import java.util.zip.Inflater; -/** Creates zlib based inflaters as necessary for object decompression. */ +/** + * Creates zlib based inflaters as necessary for object decompression. + */ public class InflaterCache { private static final int SZ = 4; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/MutableObjectId.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/MutableObjectId.java index 4b14d121e0..e492af94b9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/MutableObjectId.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/MutableObjectId.java @@ -79,15 +79,17 @@ public class MutableObjectId extends AnyObjectId { * * @param index * index of the byte to set in the raw form of the ObjectId. Must - * be in range [0, {@link Constants#OBJECT_ID_LENGTH}). + * be in range [0, + * {@link org.eclipse.jgit.lib.Constants#OBJECT_ID_LENGTH}). * @param value * the value of the specified byte at {@code index}. Values are * unsigned and thus are in the range [0,255] rather than the * signed byte range of [-128, 127]. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * {@code index} is less than 0, equal to - * {@link Constants#OBJECT_ID_LENGTH}, or greater than - * {@link Constants#OBJECT_ID_LENGTH}. + * {@link org.eclipse.jgit.lib.Constants#OBJECT_ID_LENGTH}, or + * greater than + * {@link org.eclipse.jgit.lib.Constants#OBJECT_ID_LENGTH}. */ public void setByte(int index, int value) { switch (index >> 2) { @@ -128,7 +130,9 @@ public class MutableObjectId extends AnyObjectId { } } - /** Make this id match {@link ObjectId#zeroId()}. */ + /** + * Make this id match {@link org.eclipse.jgit.lib.ObjectId#zeroId()}. + */ public void clear() { w1 = 0; w2 = 0; @@ -198,7 +202,6 @@ public class MutableObjectId extends AnyObjectId { * must be available within this integers array. * @param p * position to read the first integer of data from. - * */ public void fromRaw(final int[] ints, final int p) { w1 = ints[p]; @@ -212,10 +215,15 @@ public class MutableObjectId extends AnyObjectId { * Convert an ObjectId from binary representation expressed in integers. * * @param a + * an int. * @param b + * an int. * @param c + * an int. * @param d + * an int. * @param e + * an int. * @since 4.7 */ public void set(int a, int b, int c, int d, int e) { @@ -265,6 +273,7 @@ public class MutableObjectId extends AnyObjectId { } } + /** {@inheritDoc} */ @Override public ObjectId toObjectId() { return new ObjectId(this); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/NullProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/NullProgressMonitor.java index 497beb033a..37fcd7850f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/NullProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/NullProgressMonitor.java @@ -56,26 +56,31 @@ public class NullProgressMonitor implements ProgressMonitor { // Do not let others instantiate } + /** {@inheritDoc} */ @Override public void start(int totalTasks) { // Do not report. } + /** {@inheritDoc} */ @Override public void beginTask(String title, int totalWork) { // Do not report. } + /** {@inheritDoc} */ @Override public void update(int completed) { // Do not report. } + /** {@inheritDoc} */ @Override public boolean isCancelled() { return false; } + /** {@inheritDoc} */ @Override public void endTask() { // Do not report. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectChecker.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectChecker.java index 19c5c7eb45..a6d2c3f22c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectChecker.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectChecker.java @@ -317,12 +317,12 @@ public class ObjectChecker { * * @param objType * type of the object. Must be a valid object type code in - * {@link Constants}. + * {@link org.eclipse.jgit.lib.Constants}. * @param raw * the raw data which comprises the object. This should be in the * canonical format (that is the format used to generate the * ObjectId of the object). The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if an error is identified. */ public void check(int objType, byte[] raw) @@ -337,12 +337,12 @@ public class ObjectChecker { * identify of the object being checked. * @param objType * type of the object. Must be a valid object type code in - * {@link Constants}. + * {@link org.eclipse.jgit.lib.Constants}. * @param raw * the raw data which comprises the object. This should be in the * canonical format (that is the format used to generate the * ObjectId of the object). The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if an error is identified. * @since 4.2 */ @@ -449,7 +449,7 @@ public class ObjectChecker { * * @param raw * the commit data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. */ public void checkCommit(byte[] raw) throws CorruptObjectException { @@ -463,7 +463,7 @@ public class ObjectChecker { * identity of the object being checked. * @param raw * the commit data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. * @since 4.2 */ @@ -503,7 +503,7 @@ public class ObjectChecker { * * @param raw * the tag data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. */ public void checkTag(byte[] raw) throws CorruptObjectException { @@ -517,7 +517,7 @@ public class ObjectChecker { * identity of the object being checked. * @param raw * the tag data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. * @since 4.2 */ @@ -593,7 +593,7 @@ public class ObjectChecker { * * @param raw * the raw tree data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. */ public void checkTree(byte[] raw) throws CorruptObjectException { @@ -607,7 +607,7 @@ public class ObjectChecker { * identity of the object being checked. * @param raw * the raw tree data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. * @since 4.2 */ @@ -739,11 +739,13 @@ public class ObjectChecker { /** * Check tree path entry for validity. *

- * Unlike {@link #checkPathSegment(byte[], int, int)}, this version - * scans a multi-directory path string such as {@code "src/main.c"}. + * Unlike {@link #checkPathSegment(byte[], int, int)}, this version scans a + * multi-directory path string such as {@code "src/main.c"}. * - * @param path path string to scan. - * @throws CorruptObjectException path is invalid. + * @param path + * path string to scan. + * @throws org.eclipse.jgit.errors.CorruptObjectException + * path is invalid. * @since 3.6 */ public void checkPath(String path) throws CorruptObjectException { @@ -754,13 +756,17 @@ public class ObjectChecker { /** * Check tree path entry for validity. *

- * Unlike {@link #checkPathSegment(byte[], int, int)}, this version - * scans a multi-directory path string such as {@code "src/main.c"}. + * Unlike {@link #checkPathSegment(byte[], int, int)}, this version scans a + * multi-directory path string such as {@code "src/main.c"}. * - * @param raw buffer to scan. - * @param ptr offset to first byte of the name. - * @param end offset to one past last byte of name. - * @throws CorruptObjectException path is invalid. + * @param raw + * buffer to scan. + * @param ptr + * offset to first byte of the name. + * @param end + * offset to one past last byte of name. + * @throws org.eclipse.jgit.errors.CorruptObjectException + * path is invalid. * @since 3.6 */ public void checkPath(byte[] raw, int ptr, int end) @@ -778,10 +784,14 @@ public class ObjectChecker { /** * Check tree path entry for validity. * - * @param raw buffer to scan. - * @param ptr offset to first byte of the name. - * @param end offset to one past last byte of name. - * @throws CorruptObjectException name is invalid. + * @param raw + * buffer to scan. + * @param ptr + * offset to first byte of the name. + * @param end + * offset to one past last byte of name. + * @throws org.eclipse.jgit.errors.CorruptObjectException + * name is invalid. * @since 3.4 */ public void checkPathSegment(byte[] raw, int ptr, int end) @@ -1073,7 +1083,7 @@ public class ObjectChecker { } /** - * Create a new {@link BlobObjectChecker}. + * Create a new {@link org.eclipse.jgit.lib.BlobObjectChecker}. * * @return new BlobObjectChecker or null if it's not provided. * @since 4.9 @@ -1086,12 +1096,13 @@ public class ObjectChecker { /** * Check a blob for errors. * - *

This may not be called from PackParser in some cases. Use {@link - * #newBlobObjectChecker} instead. + *

+ * This may not be called from PackParser in some cases. Use + * {@link #newBlobObjectChecker} instead. * * @param raw * the blob data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. */ public void checkBlob(final byte[] raw) throws CorruptObjectException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectDatabase.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectDatabase.java index 2abd6dae61..bbef51da20 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectDatabase.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectDatabase.java @@ -52,10 +52,12 @@ import org.eclipse.jgit.errors.MissingObjectException; * Abstraction of arbitrary object storage. *

* An object database stores one or more Git objects, indexed by their unique - * {@link ObjectId}. + * {@link org.eclipse.jgit.lib.ObjectId}. */ public abstract class ObjectDatabase { - /** Initialize a new database instance for access. */ + /** + * Initialize a new database instance for access. + */ protected ObjectDatabase() { // Protected to force extension. } @@ -73,7 +75,7 @@ public abstract class ObjectDatabase { /** * Initialize a new object database at this location. * - * @throws IOException + * @throws java.io.IOException * the database could not be created. */ public void create() throws IOException { @@ -116,7 +118,7 @@ public abstract class ObjectDatabase { * @param objectId * identity of the object to test for existence of. * @return true if the specified object is stored in this database. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public boolean has(final AnyObjectId objectId) throws IOException { @@ -133,10 +135,10 @@ public abstract class ObjectDatabase { * * @param objectId * identity of the object to open. - * @return a {@link ObjectLoader} for accessing the object. + * @return a {@link org.eclipse.jgit.lib.ObjectLoader} for accessing the object. * @throws MissingObjectException * the object does not exist. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public ObjectLoader open(final AnyObjectId objectId) @@ -154,16 +156,17 @@ public abstract class ObjectDatabase { * identity of the object to open. * @param typeHint * hint about the type of object being requested, e.g. - * {@link Constants#OBJ_BLOB}; {@link ObjectReader#OBJ_ANY} if - * the object type is not known, or does not matter to the - * caller. - * @return a {@link ObjectLoader} for accessing the object. - * @throws MissingObjectException + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB}; + * {@link org.eclipse.jgit.lib.ObjectReader#OBJ_ANY} if the + * object type is not known, or does not matter to the caller. + * @return a {@link org.eclipse.jgit.lib.ObjectLoader} for accessing the + * object. + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * typeHint was not OBJ_ANY, and the object's actual type does * not match typeHint. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public ObjectLoader open(AnyObjectId objectId, int typeHint) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectId.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectId.java index 991f03f82e..0e85545531 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectId.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectId.java @@ -252,10 +252,15 @@ public class ObjectId extends AnyObjectId implements Serializable { * Construct an ObjectId from 160 bits provided in 5 words. * * @param new_1 + * an int * @param new_2 + * an int * @param new_3 + * an int * @param new_4 + * an int * @param new_5 + * an int * @since 4.7 */ public ObjectId(int new_1, int new_2, int new_3, int new_4, int new_5) { @@ -284,6 +289,7 @@ public class ObjectId extends AnyObjectId implements Serializable { w5 = src.w5; } + /** {@inheritDoc} */ @Override public ObjectId toObjectId() { return this; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdOwnerMap.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdOwnerMap.java index 95cb976372..03a430cab6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdOwnerMap.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdOwnerMap.java @@ -48,10 +48,12 @@ import java.util.Iterator; import java.util.NoSuchElementException; /** - * Fast, efficient map for {@link ObjectId} subclasses in only one map. + * Fast, efficient map for {@link org.eclipse.jgit.lib.ObjectId} subclasses in + * only one map. *

* To use this map type, applications must have their entry value type extend - * from {@link ObjectIdOwnerMap.Entry}, which itself extends from ObjectId. + * from {@link org.eclipse.jgit.lib.ObjectIdOwnerMap.Entry}, which itself + * extends from ObjectId. *

* Object instances may only be stored in ONE ObjectIdOwnerMap. This * restriction exists because the map stores internal map state within each @@ -59,10 +61,11 @@ import java.util.NoSuchElementException; * could corrupt one or both map's internal state. *

* If an object instance must be in more than one map, applications may use - * ObjectIdOwnerMap for one of the maps, and {@link ObjectIdSubclassMap} for the - * other map(s). It is encouraged to use ObjectIdOwnerMap for the map that is - * accessed most often, as this implementation runs faster than the more general - * ObjectIdSubclassMap implementation. + * ObjectIdOwnerMap for one of the maps, and + * {@link org.eclipse.jgit.lib.ObjectIdSubclassMap} for the other map(s). It is + * encouraged to use ObjectIdOwnerMap for the map that is accessed most often, + * as this implementation runs faster than the more general ObjectIdSubclassMap + * implementation. * * @param * type of subclass of ObjectId that will be stored in the map. @@ -97,7 +100,9 @@ public class ObjectIdOwnerMap /** Low bit mask to index into {@link #directory}, {@code 2^bits-1}. */ private int mask; - /** Create an empty map. */ + /** + * Create an empty map. + */ @SuppressWarnings("unchecked") public ObjectIdOwnerMap() { bits = 0; @@ -108,7 +113,9 @@ public class ObjectIdOwnerMap directory[0] = newSegment(); } - /** Remove all entries from this map. */ + /** + * Remove all entries from this map. + */ public void clear() { size = 0; @@ -137,11 +144,9 @@ public class ObjectIdOwnerMap } /** + * {@inheritDoc} + *

* Returns true if this map contains the specified object. - * - * @param toFind - * object to find. - * @return true if the mapping exists for this object; false otherwise. */ @Override public boolean contains(final AnyObjectId toFind) { @@ -157,8 +162,6 @@ public class ObjectIdOwnerMap * * @param newValue * the object to store. - * @param - * type of instance to store. */ public void add(final Q newValue) { if (++size == grow) @@ -189,8 +192,6 @@ public class ObjectIdOwnerMap * @return {@code newValue} if stored, or the prior value already stored and * that would have been returned had the caller used * {@code get(newValue)} first. - * @param - * type of instance to store. */ @SuppressWarnings("unchecked") public V addIfAbsent(final Q newValue) { @@ -210,16 +211,25 @@ public class ObjectIdOwnerMap return newValue; } - /** @return number of objects in this map. */ + /** + * Get number of objects in this map. + * + * @return number of objects in this map. + */ public int size() { return size; } - /** @return true if {@link #size()} is 0. */ + /** + * Whether this map is empty + * + * @return true if {@link #size()} is 0. + */ public boolean isEmpty() { return size == 0; } + /** {@inheritDoc} */ @Override public Iterator iterator() { return new Iterator() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdRef.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdRef.java index 636716bcb3..22aaa3ad73 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdRef.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdRef.java @@ -47,7 +47,10 @@ package org.eclipse.jgit.lib; import org.eclipse.jgit.annotations.NonNull; import org.eclipse.jgit.annotations.Nullable; -/** A {@link Ref} that points directly at an {@link ObjectId}. */ +/** + * A {@link org.eclipse.jgit.lib.Ref} that points directly at an + * {@link org.eclipse.jgit.lib.ObjectId}. + */ public abstract class ObjectIdRef implements Ref { /** Any reference whose peeled value is not yet known. */ public static class Unpeeled extends ObjectIdRef { @@ -167,41 +170,48 @@ public abstract class ObjectIdRef implements Ref { this.objectId = id; } + /** {@inheritDoc} */ @Override @NonNull public String getName() { return name; } + /** {@inheritDoc} */ @Override public boolean isSymbolic() { return false; } + /** {@inheritDoc} */ @Override @NonNull public Ref getLeaf() { return this; } + /** {@inheritDoc} */ @Override @NonNull public Ref getTarget() { return this; } + /** {@inheritDoc} */ @Override @Nullable public ObjectId getObjectId() { return objectId; } + /** {@inheritDoc} */ @Override @NonNull public Storage getStorage() { return storage; } + /** {@inheritDoc} */ @NonNull @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSet.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSet.java index 0b5848463c..51bd9029a0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSet.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSet.java @@ -48,7 +48,8 @@ package org.eclipse.jgit.lib; *

* Usually backed by a read-only data structure such as * {@link org.eclipse.jgit.internal.storage.file.PackIndex}. Mutable types like - * {@link ObjectIdOwnerMap} also implement the interface by checking keys. + * {@link org.eclipse.jgit.lib.ObjectIdOwnerMap} also implement the interface by + * checking keys. * * @since 4.2 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSubclassMap.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSubclassMap.java index 43fc7bfb97..001aa9cdd6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSubclassMap.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSubclassMap.java @@ -49,13 +49,15 @@ import java.util.Iterator; import java.util.NoSuchElementException; /** - * Fast, efficient map specifically for {@link ObjectId} subclasses. + * Fast, efficient map specifically for {@link org.eclipse.jgit.lib.ObjectId} + * subclasses. *

* This map provides an efficient translation from any ObjectId instance to a * cached subclass of ObjectId that has the same value. *

- * If object instances are stored in only one map, {@link ObjectIdOwnerMap} is a - * more efficient implementation. + * If object instances are stored in only one map, + * {@link org.eclipse.jgit.lib.ObjectIdOwnerMap} is a more efficient + * implementation. * * @param * type of subclass of ObjectId that will be stored in the map. @@ -72,12 +74,16 @@ public class ObjectIdSubclassMap V[] table; - /** Create an empty map. */ + /** + * Create an empty map. + */ public ObjectIdSubclassMap() { initTable(INITIAL_TABLE_SIZE); } - /** Remove all entries from this map. */ + /** + * Remove all entries from this map. + */ public void clear() { size = 0; initTable(INITIAL_TABLE_SIZE); @@ -105,11 +111,9 @@ public class ObjectIdSubclassMap } /** + * {@inheritDoc} + *

* Returns true if this map contains the specified object. - * - * @param toFind - * object to find. - * @return true if the mapping exists for this object; false otherwise. */ @Override public boolean contains(final AnyObjectId toFind) { @@ -126,8 +130,6 @@ public class ObjectIdSubclassMap * * @param newValue * the object to store. - * @param - * type of instance to store. */ public void add(final Q newValue) { if (++size == grow) @@ -152,8 +154,6 @@ public class ObjectIdSubclassMap * @return {@code newValue} if stored, or the prior value already stored and * that would have been returned had the caller used * {@code get(newValue)} first. - * @param - * type of instance to store. */ public V addIfAbsent(final Q newValue) { final int msk = mask; @@ -177,17 +177,24 @@ public class ObjectIdSubclassMap } /** + * Get number of objects in map + * * @return number of objects in map */ public int size() { return size; } - /** @return true if {@link #size()} is 0. */ + /** + * Whether {@link #size()} is 0. + * + * @return true if {@link #size()} is 0. + */ public boolean isEmpty() { return size == 0; } + /** {@inheritDoc} */ @Override public Iterator iterator() { return new Iterator() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java index 857ec9b2df..f334ff7786 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java @@ -182,7 +182,9 @@ public abstract class ObjectInserter implements AutoCloseable { /** Temporary working buffer for streaming data through. */ private byte[] tempBuffer; - /** Create a new inserter for a database. */ + /** + * Create a new inserter for a database. + */ protected ObjectInserter() { } @@ -218,6 +220,8 @@ public abstract class ObjectInserter implements AutoCloseable { } /** + * Compute digest to help compute an ObjectId + * * @return digest to help compute an ObjectId * @since 4.7 */ @@ -272,7 +276,7 @@ public abstract class ObjectInserter implements AutoCloseable { * stream providing the object content. The caller is responsible * for closing the stream. * @return the name of the object. - * @throws IOException + * @throws java.io.IOException * the source stream could not be read. */ public ObjectId idFor(int objectType, long length, InputStream in) @@ -297,6 +301,7 @@ public abstract class ObjectInserter implements AutoCloseable { * Compute the ObjectId for the given tree without inserting it. * * @param formatter + * a {@link org.eclipse.jgit.lib.TreeFormatter} object. * @return the computed ObjectId */ public ObjectId idFor(TreeFormatter formatter) { @@ -309,7 +314,7 @@ public abstract class ObjectInserter implements AutoCloseable { * @param formatter * the formatter containing the proposed tree's data. * @return the name of the tree object. - * @throws IOException + * @throws java.io.IOException * the object could not be stored. */ public final ObjectId insert(TreeFormatter formatter) throws IOException { @@ -325,7 +330,7 @@ public abstract class ObjectInserter implements AutoCloseable { * @param builder * the builder containing the proposed commit's data. * @return the name of the commit object. - * @throws IOException + * @throws java.io.IOException * the object could not be stored. */ public final ObjectId insert(CommitBuilder builder) throws IOException { @@ -338,7 +343,7 @@ public abstract class ObjectInserter implements AutoCloseable { * @param builder * the builder containing the proposed tag's data. * @return the name of the tag object. - * @throws IOException + * @throws java.io.IOException * the object could not be stored. */ public final ObjectId insert(TagBuilder builder) throws IOException { @@ -353,7 +358,7 @@ public abstract class ObjectInserter implements AutoCloseable { * @param data * complete content of the object. * @return the name of the object. - * @throws IOException + * @throws java.io.IOException * the object could not be stored. */ public ObjectId insert(final int type, final byte[] data) @@ -373,7 +378,7 @@ public abstract class ObjectInserter implements AutoCloseable { * @param len * number of bytes to copy from {@code data}. * @return the name of the object. - * @throws IOException + * @throws java.io.IOException * the object could not be stored. */ public ObjectId insert(int type, byte[] data, int off, int len) @@ -392,7 +397,7 @@ public abstract class ObjectInserter implements AutoCloseable { * stream providing the object content. The caller is responsible * for closing the stream. * @return the name of the object. - * @throws IOException + * @throws java.io.IOException * the object could not be stored, or the source stream could * not be read. */ @@ -406,7 +411,7 @@ public abstract class ObjectInserter implements AutoCloseable { * the input stream. The stream is not closed by the parser, and * must instead be closed by the caller once parsing is complete. * @return the pack parser. - * @throws IOException + * @throws java.io.IOException * the parser instance, which can be configured and then used to * parse objects into the ObjectDatabase. */ @@ -436,13 +441,15 @@ public abstract class ObjectInserter implements AutoCloseable { * The flush may take some period of time to make the objects available to * other threads. * - * @throws IOException + * @throws java.io.IOException * the flush could not be completed; objects inserted thus far * are in an indeterminate state. */ public abstract void flush() throws IOException; /** + * {@inheritDoc} + *

* Release any resources used by this inserter. *

* An inserter that has been released can be used again, but may need to be diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectLoader.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectLoader.java index e66536168e..432f5a6cd9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectLoader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectLoader.java @@ -61,16 +61,23 @@ import org.eclipse.jgit.util.IO; */ public abstract class ObjectLoader { /** - * @return Git in pack object type, see {@link Constants}. + * Get Git in pack object type + * + * @return Git in pack object type, see + * {@link org.eclipse.jgit.lib.Constants}. */ public abstract int getType(); /** + * Get size of object in bytes + * * @return size of object in bytes */ public abstract long getSize(); /** + * Whether this object is too large to obtain as a byte array. + * * @return true if this object is too large to obtain as a byte array. * Objects over a certain threshold should be accessed only by their * {@link #openStream()} to prevent overflowing the JVM heap. @@ -91,7 +98,7 @@ public abstract class ObjectLoader { * be modified by the caller. * * @return the bytes of this object. - * @throws LargeObjectException + * @throws org.eclipse.jgit.errors.LargeObjectException * if the object won't fit into a byte array, because * {@link #isLarge()} returns true. Callers should use * {@link #openStream()} instead to access the contents. @@ -113,16 +120,18 @@ public abstract class ObjectLoader { * * @param sizeLimit * maximum number of bytes to return. If the object is larger - * than this limit, {@link LargeObjectException} will be thrown. + * than this limit, + * {@link org.eclipse.jgit.errors.LargeObjectException} will be + * thrown. * @return the bytes of this object. - * @throws LargeObjectException + * @throws org.eclipse.jgit.errors.LargeObjectException * if the object is bigger than {@code sizeLimit}, or if - * {@link OutOfMemoryError} occurs during allocation of the - * result array. Callers should use {@link #openStream()} + * {@link java.lang.OutOfMemoryError} occurs during allocation + * of the result array. Callers should use {@link #openStream()} * instead to access the contents. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object is large, and it no longer exists. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public final byte[] getBytes(int sizeLimit) throws LargeObjectException, @@ -144,7 +153,7 @@ public abstract class ObjectLoader { * Changes (if made) will affect the cache but not the repository itself. * * @return the cached bytes of this object. Do not modify it. - * @throws LargeObjectException + * @throws org.eclipse.jgit.errors.LargeObjectException * if the object won't fit into a byte array, because * {@link #isLarge()} returns true. Callers should use * {@link #openStream()} instead to access the contents. @@ -167,16 +176,17 @@ public abstract class ObjectLoader { * @param sizeLimit * maximum number of bytes to return. If the object size is * larger than this limit and {@link #isLarge()} is true, - * {@link LargeObjectException} will be thrown. + * {@link org.eclipse.jgit.errors.LargeObjectException} will be + * thrown. * @return the cached bytes of this object. Do not modify it. - * @throws LargeObjectException + * @throws org.eclipse.jgit.errors.LargeObjectException * if the object is bigger than {@code sizeLimit}, or if - * {@link OutOfMemoryError} occurs during allocation of the - * result array. Callers should use {@link #openStream()} + * {@link java.lang.OutOfMemoryError} occurs during allocation + * of the result array. Callers should use {@link #openStream()} * instead to access the contents. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object is large, and it no longer exists. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public byte[] getCachedBytes(int sizeLimit) throws LargeObjectException, @@ -213,9 +223,9 @@ public abstract class ObjectLoader { * @return a stream of this object's data. Caller must close the stream when * through with it. The returned stream is buffered with a * reasonable buffer size. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object no longer exists. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public abstract ObjectStream openStream() throws MissingObjectException, @@ -236,9 +246,9 @@ public abstract class ObjectLoader { * stream to receive the complete copy of this object's data. * Caller is responsible for flushing or closing this stream * after this method returns. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object no longer exists. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed, or the stream cannot be * written to. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectReader.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectReader.java index f39f291899..700b9dbe85 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectReader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectReader.java @@ -53,13 +53,13 @@ import java.util.Set; import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.MissingObjectException; -import org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs; /** - * Reads an {@link ObjectDatabase} for a single thread. + * Reads an {@link org.eclipse.jgit.lib.ObjectDatabase} for a single thread. *

* Readers that can support efficient reuse of pack encoded objects should also - * implement the companion interface {@link ObjectReuseAsIs}. + * implement the companion interface + * {@link org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs}. */ public abstract class ObjectReader implements AutoCloseable { /** Type hint indicating the caller doesn't know the type. */ @@ -95,7 +95,7 @@ public abstract class ObjectReader implements AutoCloseable { * @param objectId * object identity that needs to be abbreviated. * @return SHA-1 abbreviation. - * @throws IOException + * @throws java.io.IOException * the object store cannot be read. */ public AbbreviatedObjectId abbreviate(AnyObjectId objectId) @@ -122,7 +122,7 @@ public abstract class ObjectReader implements AutoCloseable { * [2, {@value Constants#OBJECT_ID_STRING_LENGTH}]. * @return SHA-1 abbreviation. If no matching objects exist in the * repository, the abbreviation will match the minimum length. - * @throws IOException + * @throws java.io.IOException * the object store cannot be read. */ public AbbreviatedObjectId abbreviate(AnyObjectId objectId, int len) @@ -174,7 +174,7 @@ public abstract class ObjectReader implements AutoCloseable { * abbreviated id to resolve to a complete identity. The * abbreviation must have a length of at least 2. * @return candidates that begin with the abbreviated identity. - * @throws IOException + * @throws java.io.IOException * the object store cannot be read. */ public abstract Collection resolve(AbbreviatedObjectId id) @@ -186,7 +186,7 @@ public abstract class ObjectReader implements AutoCloseable { * @param objectId * identity of the object to test for existence of. * @return true if the specified object is stored in this database. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public boolean has(AnyObjectId objectId) throws IOException { @@ -200,13 +200,14 @@ public abstract class ObjectReader implements AutoCloseable { * identity of the object to test for existence of. * @param typeHint * hint about the type of object being requested, e.g. - * {@link Constants#OBJ_BLOB}; {@link #OBJ_ANY} if the object - * type is not known, or does not matter to the caller. + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB}; + * {@link #OBJ_ANY} if the object type is not known, or does not + * matter to the caller. * @return true if the specified object is stored in this database. * @throws IncorrectObjectTypeException * typeHint was not OBJ_ANY, and the object's actual type does * not match typeHint. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public boolean has(AnyObjectId objectId, int typeHint) throws IOException { @@ -223,10 +224,11 @@ public abstract class ObjectReader implements AutoCloseable { * * @param objectId * identity of the object to open. - * @return a {@link ObjectLoader} for accessing the object. - * @throws MissingObjectException + * @return a {@link org.eclipse.jgit.lib.ObjectLoader} for accessing the + * object. + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public ObjectLoader open(AnyObjectId objectId) @@ -241,15 +243,17 @@ public abstract class ObjectReader implements AutoCloseable { * identity of the object to open. * @param typeHint * hint about the type of object being requested, e.g. - * {@link Constants#OBJ_BLOB}; {@link #OBJ_ANY} if the object - * type is not known, or does not matter to the caller. - * @return a {@link ObjectLoader} for accessing the object. - * @throws MissingObjectException + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB}; + * {@link #OBJ_ANY} if the object type is not known, or does not + * matter to the caller. + * @return a {@link org.eclipse.jgit.lib.ObjectLoader} for accessing the + * object. + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * typeHint was not OBJ_ANY, and the object's actual type does * not match typeHint. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public abstract ObjectLoader open(AnyObjectId objectId, int typeHint) @@ -260,15 +264,13 @@ public abstract class ObjectReader implements AutoCloseable { * Returns IDs for those commits which should be considered as shallow. * * @return IDs of shallow commits - * @throws IOException + * @throws java.io.IOException */ public abstract Set getShallowCommits() throws IOException; /** * Asynchronous object opening. * - * @param - * type of identifier being supplied. * @param objectIds * objects to open from the object store. The supplied collection * must not be modified until the queue has finished. @@ -335,15 +337,16 @@ public abstract class ObjectReader implements AutoCloseable { * identity of the object to open. * @param typeHint * hint about the type of object being requested, e.g. - * {@link Constants#OBJ_BLOB}; {@link #OBJ_ANY} if the object - * type is not known, or does not matter to the caller. + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB}; + * {@link #OBJ_ANY} if the object type is not known, or does not + * matter to the caller. * @return size of object in bytes. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * typeHint was not OBJ_ANY, and the object's actual type does * not match typeHint. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public long getObjectSize(AnyObjectId objectId, int typeHint) @@ -355,8 +358,6 @@ public abstract class ObjectReader implements AutoCloseable { /** * Asynchronous object size lookup. * - * @param - * type of identifier being supplied. * @param objectIds * objects to get the size of from the object store. The supplied * collection must not be modified until the queue has finished. @@ -433,7 +434,7 @@ public abstract class ObjectReader implements AutoCloseable { * An index that can be used to speed up ObjectWalks. * * @return the index or null if one does not exist. - * @throws IOException + * @throws java.io.IOException * when the index fails to load * @since 3.0 */ @@ -442,9 +443,12 @@ public abstract class ObjectReader implements AutoCloseable { } /** - * @return the {@link ObjectInserter} from which this reader was created - * using {@code inserter.newReader()}, or null if this reader was not - * created from an inserter. + * Get the {@link org.eclipse.jgit.lib.ObjectInserter} from which this + * reader was created using {@code inserter.newReader()} + * + * @return the {@link org.eclipse.jgit.lib.ObjectInserter} from which this + * reader was created using {@code inserter.newReader()}, or null if + * this reader was not created from an inserter. * @since 4.4 */ @Nullable @@ -453,6 +457,8 @@ public abstract class ObjectReader implements AutoCloseable { } /** + * {@inheritDoc} + *

* Release any resources used by this reader. *

* A reader that has been released can be used again, but may need to be diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectStream.java index 4b3fe6af57..ad123c4a3a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectStream.java @@ -46,12 +46,22 @@ package org.eclipse.jgit.lib; import java.io.IOException; import java.io.InputStream; -/** Stream of data coming from an object loaded by {@link ObjectLoader}. */ +/** + * Stream of data coming from an object loaded by {@link org.eclipse.jgit.lib.ObjectLoader}. + */ public abstract class ObjectStream extends InputStream { - /** @return Git object type, see {@link Constants}. */ + /** + * Get Git object type, see {@link Constants}. + * + * @return Git object type, see {@link Constants}. + */ public abstract int getType(); - /** @return total size of object in bytes */ + /** + * Get total size of object in bytes + * + * @return total size of object in bytes + */ public abstract long getSize(); /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java index 45757e42f5..18a11f0015 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java @@ -65,6 +65,8 @@ public class PersonIdent implements Serializable { private static final long serialVersionUID = 1L; /** + * Get timezone object for the given offset. + * * @param tzOffset * timezone offset as in {@link #getTimeZoneOffset()}. * @return time zone object for the given offset. @@ -163,38 +165,45 @@ public class PersonIdent implements Serializable { * This new PersonIdent gets the info from the default committer as available * from the configuration. * - * @param repo + * @param repo a {@link org.eclipse.jgit.lib.Repository} object. */ public PersonIdent(final Repository repo) { this(repo.getConfig().get(UserConfig.KEY)); } /** - * Copy a {@link PersonIdent}. + * Copy a {@link org.eclipse.jgit.lib.PersonIdent}. * * @param pi - * Original {@link PersonIdent} + * Original {@link org.eclipse.jgit.lib.PersonIdent} */ public PersonIdent(final PersonIdent pi) { this(pi.getName(), pi.getEmailAddress()); } /** - * Construct a new {@link PersonIdent} with current time. + * Construct a new {@link org.eclipse.jgit.lib.PersonIdent} with current + * time. * * @param aName + * a {@link java.lang.String} object. * @param aEmailAddress + * a {@link java.lang.String} object. */ public PersonIdent(final String aName, final String aEmailAddress) { this(aName, aEmailAddress, SystemReader.getInstance().getCurrentTime()); } /** - * Construct a new {@link PersonIdent} with current time. + * Construct a new {@link org.eclipse.jgit.lib.PersonIdent} with current + * time. * * @param aName + * a {@link java.lang.String} object. * @param aEmailAddress + * a {@link java.lang.String} object. * @param when + * a {@link org.eclipse.jgit.util.time.ProposedTimestamp} object. * @since 4.6 */ public PersonIdent(String aName, String aEmailAddress, @@ -206,7 +215,7 @@ public class PersonIdent implements Serializable { * Copy a PersonIdent, but alter the clone's time stamp * * @param pi - * original {@link PersonIdent} + * original {@link org.eclipse.jgit.lib.PersonIdent} * @param when * local time * @param tz @@ -217,10 +226,11 @@ public class PersonIdent implements Serializable { } /** - * Copy a {@link PersonIdent}, but alter the clone's time stamp + * Copy a {@link org.eclipse.jgit.lib.PersonIdent}, but alter the clone's + * time stamp * * @param pi - * original {@link PersonIdent} + * original {@link org.eclipse.jgit.lib.PersonIdent} * @param aWhen * local time */ @@ -231,8 +241,8 @@ public class PersonIdent implements Serializable { /** * Construct a PersonIdent from simple data * - * @param aName - * @param aEmailAddress + * @param aName a {@link java.lang.String} object. + * @param aEmailAddress a {@link java.lang.String} object. * @param aWhen * local time stamp * @param aTZ @@ -248,7 +258,7 @@ public class PersonIdent implements Serializable { * Copy a PersonIdent, but alter the clone's time stamp * * @param pi - * original {@link PersonIdent} + * original {@link org.eclipse.jgit.lib.PersonIdent} * @param aWhen * local time stamp * @param aTZ @@ -269,7 +279,7 @@ public class PersonIdent implements Serializable { } /** - * Construct a {@link PersonIdent}. + * Construct a {@link org.eclipse.jgit.lib.PersonIdent}. *

* Whitespace in the name and email is preserved for the lifetime of this * object, but are trimmed by {@link #toExternalString()}. This means that @@ -277,7 +287,9 @@ public class PersonIdent implements Serializable { * equivalent instance. * * @param aName + * a {@link java.lang.String} object. * @param aEmailAddress + * a {@link java.lang.String} object. * @param aWhen * local time stamp * @param aTZ @@ -298,6 +310,8 @@ public class PersonIdent implements Serializable { } /** + * Get name of person + * * @return Name of person */ public String getName() { @@ -305,6 +319,8 @@ public class PersonIdent implements Serializable { } /** + * Get email address of person + * * @return email address of person */ public String getEmailAddress() { @@ -312,6 +328,8 @@ public class PersonIdent implements Serializable { } /** + * Get timestamp + * * @return timestamp */ public Date getWhen() { @@ -319,6 +337,8 @@ public class PersonIdent implements Serializable { } /** + * Get this person's declared time zone + * * @return this person's declared time zone; null if time zone is unknown. */ public TimeZone getTimeZone() { @@ -326,6 +346,8 @@ public class PersonIdent implements Serializable { } /** + * Get this person's declared time zone as minutes east of UTC. + * * @return this person's declared time zone as minutes east of UTC. If the * timezone is to the west of UTC it is negative. */ @@ -334,6 +356,8 @@ public class PersonIdent implements Serializable { } /** + * {@inheritDoc} + *

* Hashcode is based only on the email address and timestamp. */ @Override @@ -344,6 +368,7 @@ public class PersonIdent implements Serializable { return hc; } + /** {@inheritDoc} */ @Override public boolean equals(final Object o) { if (o instanceof PersonIdent) { @@ -372,6 +397,7 @@ public class PersonIdent implements Serializable { return r.toString(); } + /** {@inheritDoc} */ @Override @SuppressWarnings("nls") public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ProgressMonitor.java index 7748140e2c..d81ee45c9e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ProgressMonitor.java @@ -44,7 +44,9 @@ package org.eclipse.jgit.lib; -/** A progress reporting interface. */ +/** + * A progress reporting interface. + */ public interface ProgressMonitor { /** Constant indicating the total work units cannot be predicted. */ public static final int UNKNOWN = 0; @@ -85,7 +87,9 @@ public interface ProgressMonitor { */ void update(int completed); - /** Finish the current task, so the next can begin. */ + /** + * Finish the current task, so the next can begin. + */ void endTask(); /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoFile.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoFile.java index c4923a359e..06b4b227c8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoFile.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoFile.java @@ -67,7 +67,10 @@ public class RebaseTodoFile { private Repository repo; /** + * Constructor for RebaseTodoFile. + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ public RebaseTodoFile(Repository repo) { this.repo = repo; @@ -84,7 +87,7 @@ public class RebaseTodoFile { * @param includeComments * true if also comments should be reported * @return the list of steps - * @throws IOException + * @throws java.io.IOException */ public List readRebaseTodo(String path, boolean includeComments) throws IOException { @@ -214,7 +217,7 @@ public class RebaseTodoFile { * the steps to be written * @param append * whether to append to an existing file or to write a new file - * @throws IOException + * @throws java.io.IOException */ public void writeRebaseTodoFile(String path, List steps, boolean append) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoLine.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoLine.java index 9af8d76910..4e235b05c0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoLine.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoLine.java @@ -142,8 +142,11 @@ public class RebaseTodoLine { * Create a new non-comment line * * @param action + * a {@link org.eclipse.jgit.lib.RebaseTodoLine.Action} object. * @param commit + * a {@link org.eclipse.jgit.lib.AbbreviatedObjectId} object. * @param shortMessage + * a {@link java.lang.String} object. */ public RebaseTodoLine(Action action, AbbreviatedObjectId commit, String shortMessage) { @@ -154,6 +157,8 @@ public class RebaseTodoLine { } /** + * Get rebase action type + * * @return rebase action type */ public Action getAction() { @@ -167,7 +172,8 @@ public class RebaseTodoLine { * non-comment. * * @param newAction - * @throws IllegalTodoFileModification + * a {@link org.eclipse.jgit.lib.RebaseTodoLine.Action} object. + * @throws org.eclipse.jgit.errors.IllegalTodoFileModification * on attempt to set a non-comment action on a line which was a * comment line before. */ @@ -193,7 +199,7 @@ public class RebaseTodoLine { /** *

* Set a comment for this line that is used if this line's - * {@link RebaseTodoLine#action} is a {@link Action#COMMENT} + * {@link org.eclipse.jgit.lib.RebaseTodoLine#action} is a {@link org.eclipse.jgit.lib.RebaseTodoLine.Action#COMMENT} *

* It's allowed to unset the comment by calling * setComment(null)
@@ -230,6 +236,8 @@ public class RebaseTodoLine { } /** + * Get abbreviated commit SHA-1 of commit that action will be performed on + * * @return abbreviated commit SHA-1 of commit that action will be performed * on */ @@ -238,6 +246,9 @@ public class RebaseTodoLine { } /** + * Get the first line of the commit message of the commit the action will be + * performed on. + * * @return the first line of the commit message of the commit the action * will be performed on. */ @@ -246,13 +257,18 @@ public class RebaseTodoLine { } /** + * Set short message + * * @param shortMessage + * a short message. */ public void setShortMessage(String shortMessage) { this.shortMessage = shortMessage; } /** + * Get a comment + * * @return a comment. If the line is a comment line then the comment is * returned. Lines starting with # or blank lines or lines * containing only spaces and tabs are considered as comment lines. @@ -262,6 +278,7 @@ public class RebaseTodoLine { return comment; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java index a78a90fe58..395bb323de 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java @@ -47,7 +47,8 @@ import org.eclipse.jgit.annotations.NonNull; import org.eclipse.jgit.annotations.Nullable; /** - * Pairing of a name and the {@link ObjectId} it currently has. + * Pairing of a name and the {@link org.eclipse.jgit.lib.ObjectId} it currently + * has. *

* A ref in Git is (more or less) a variable that holds a single object * identifier. The object identifier can be any valid Git object (blob, tree, @@ -135,9 +136,10 @@ public interface Ref { /** * Test if this reference is a symbolic reference. *

- * A symbolic reference does not have its own {@link ObjectId} value, but - * instead points to another {@code Ref} in the same database and always - * uses that other reference's value as its own. + * A symbolic reference does not have its own + * {@link org.eclipse.jgit.lib.ObjectId} value, but instead points to + * another {@code Ref} in the same database and always uses that other + * reference's value as its own. * * @return true if this is a symbolic reference; false if this reference * contains its own ObjectId. @@ -199,7 +201,9 @@ public interface Ref { public abstract ObjectId getPeeledObjectId(); /** - * @return whether the Ref represents a peeled tag + * Whether the Ref represents a peeled tag. + * + * @return whether the Ref represents a peeled tag. */ public abstract boolean isPeeled(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefComparator.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefComparator.java index 95e338685a..43d2f3766c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefComparator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefComparator.java @@ -60,6 +60,7 @@ public class RefComparator implements Comparator { /** Singleton instance of RefComparator */ public static final RefComparator INSTANCE = new RefComparator(); + /** {@inheritDoc} */ @Override public int compare(final Ref o1, final Ref o2) { return compareTo(o1, o2); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefDatabase.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefDatabase.java index 59a104b60f..557bdb994f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefDatabase.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefDatabase.java @@ -55,11 +55,13 @@ import org.eclipse.jgit.annotations.NonNull; import org.eclipse.jgit.annotations.Nullable; /** - * Abstraction of name to {@link ObjectId} mapping. + * Abstraction of name to {@link org.eclipse.jgit.lib.ObjectId} mapping. *

- * A reference database stores a mapping of reference names to {@link ObjectId}. - * Every {@link Repository} has a single reference database, mapping names to - * the tips of the object graph contained by the {@link ObjectDatabase}. + * A reference database stores a mapping of reference names to + * {@link org.eclipse.jgit.lib.ObjectId}. Every + * {@link org.eclipse.jgit.lib.Repository} has a single reference database, + * mapping names to the tips of the object graph contained by the + * {@link org.eclipse.jgit.lib.ObjectDatabase}. */ public abstract class RefDatabase { /** @@ -93,12 +95,14 @@ public abstract class RefDatabase { /** * Initialize a new reference database at this location. * - * @throws IOException + * @throws java.io.IOException * the database could not be created. */ public abstract void create() throws IOException; - /** Close any resources held by this database. */ + /** + * Close any resources held by this database. + */ public abstract void close(); /** @@ -118,7 +122,7 @@ public abstract class RefDatabase { * proposed name. * @return true if the name overlaps with an existing reference; false if * using this name right now would be safe. - * @throws IOException + * @throws java.io.IOException * the database could not be read to check for conflicts. * @see #getConflictingNames(String) */ @@ -133,7 +137,7 @@ public abstract class RefDatabase { * @return a collection of full names of existing refs which would conflict * with the passed ref name; empty collection when there are no * conflicts - * @throws IOException + * @throws java.io.IOException * @since 2.3 * @see #isNameConflicting(String) */ @@ -167,12 +171,13 @@ public abstract class RefDatabase { * the name of the reference. * @param detach * if {@code true} and {@code name} is currently a - * {@link SymbolicRef}, the update will replace it with an - * {@link ObjectIdRef}. Otherwise, the update will recursively - * traverse {@link SymbolicRef}s and operate on the leaf - * {@link ObjectIdRef}. + * {@link org.eclipse.jgit.lib.SymbolicRef}, the update will + * replace it with an {@link org.eclipse.jgit.lib.ObjectIdRef}. + * Otherwise, the update will recursively traverse + * {@link org.eclipse.jgit.lib.SymbolicRef}s and operate on the + * leaf {@link org.eclipse.jgit.lib.ObjectIdRef}. * @return a new update for the requested name; never null. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. */ @NonNull @@ -187,7 +192,7 @@ public abstract class RefDatabase { * @param toName * name of reference to rename to * @return an update command that knows how to rename a branch to another. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. */ @NonNull @@ -210,20 +215,21 @@ public abstract class RefDatabase { * Whether the database is capable of performing batch updates as atomic * transactions. *

- * If true, by default {@link BatchRefUpdate} instances will perform updates - * atomically, meaning either all updates will succeed, or all updates will - * fail. It is still possible to turn off this behavior on a per-batch basis - * by calling {@code update.setAtomic(false)}. + * If true, by default {@link org.eclipse.jgit.lib.BatchRefUpdate} instances + * will perform updates atomically, meaning either all updates will succeed, + * or all updates will fail. It is still possible to turn off this behavior + * on a per-batch basis by calling {@code update.setAtomic(false)}. *

- * If false, {@link BatchRefUpdate} instances will never perform updates - * atomically, and calling {@code update.setAtomic(true)} will cause the - * entire batch to fail with {@code REJECTED_OTHER_REASON}. + * If false, {@link org.eclipse.jgit.lib.BatchRefUpdate} instances will + * never perform updates atomically, and calling + * {@code update.setAtomic(true)} will cause the entire batch to fail with + * {@code REJECTED_OTHER_REASON}. *

* This definition of atomicity is stronger than what is provided by * {@link org.eclipse.jgit.transport.ReceivePack}. {@code ReceivePack} will * attempt to reject all commands if it knows in advance some commands may - * fail, even if the storage layer does not support atomic transactions. Here, - * atomicity applies even in the case of unforeseeable errors. + * fail, even if the storage layer does not support atomic transactions. + * Here, atomicity applies even in the case of unforeseeable errors. * * @return whether transactions are atomic by default. * @since 3.6 @@ -246,7 +252,7 @@ public abstract class RefDatabase { * the name of the reference. May be a short name which must be * searched for using the standard {@link #SEARCH_PATH}. * @return the reference (if it exists); else {@code null}. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. */ @Nullable @@ -261,7 +267,7 @@ public abstract class RefDatabase { * @param name * the unabbreviated name of the reference. * @return the reference (if it exists); else {@code null}. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. * @since 4.1 */ @@ -285,7 +291,7 @@ public abstract class RefDatabase { * the unabbreviated names of references to look up. * @return modifiable map describing any refs that exist among the ref * ref names supplied. The map can be an unsorted map. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. * @since 4.1 */ @@ -310,7 +316,7 @@ public abstract class RefDatabase { * @param refs * the unabbreviated names of references to look up. * @return the first named reference that exists (if any); else {@code null}. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. * @since 4.1 */ @@ -335,7 +341,7 @@ public abstract class RefDatabase { * @return modifiable map that is a complete snapshot of the current * reference namespace, with {@code prefix} removed from the start * of each key. The map can be an unsorted map. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. */ @NonNull @@ -350,7 +356,7 @@ public abstract class RefDatabase { * and {@link #exactRef(String)}. * * @return a list of additional refs - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. */ @NonNull @@ -360,10 +366,11 @@ public abstract class RefDatabase { * Peel a possibly unpeeled reference by traversing the annotated tags. *

* If the reference cannot be peeled (as it does not refer to an annotated - * tag) the peeled id stays null, but {@link Ref#isPeeled()} will be true. + * tag) the peeled id stays null, but + * {@link org.eclipse.jgit.lib.Ref#isPeeled()} will be true. *

- * Implementors should check {@link Ref#isPeeled()} before performing any - * additional work effort. + * Implementors should check {@link org.eclipse.jgit.lib.Ref#isPeeled()} + * before performing any additional work effort. * * @param ref * The reference to peel @@ -371,7 +378,7 @@ public abstract class RefDatabase { * Ref object representing the same data as Ref, but isPeeled() will * be true and getPeeledObjectId() will contain the peeled object * (or {@code null}). - * @throws IOException + * @throws java.io.IOException * the reference space or object space cannot be accessed. */ @NonNull diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefRename.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefRename.java index 59f852b8c7..3d22bb0fc5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefRename.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefRename.java @@ -86,7 +86,11 @@ public abstract class RefRename { + Repository.shortenRefName(destination.getName())); } - /** @return identity of the user making the change in the reflog. */ + /** + * Get identity of the user making the change in the reflog. + * + * @return identity of the user making the change in the reflog. + */ public PersonIdent getRefLogIdent() { return destination.getRefLogIdent(); } @@ -130,12 +134,16 @@ public abstract class RefRename { destination.setRefLogMessage(msg, false); } - /** Don't record this rename in the ref's associated reflog. */ + /** + * Don't record this rename in the ref's associated reflog. + */ public void disableRefLog() { destination.setRefLogMessage("", false); //$NON-NLS-1$ } /** + * Get result of rename operation + * * @return result of rename operation */ public Result getResult() { @@ -143,8 +151,10 @@ public abstract class RefRename { } /** + * Rename + * * @return the result of the new ref update - * @throws IOException + * @throws java.io.IOException */ public Result rename() throws IOException { try { @@ -157,15 +167,20 @@ public abstract class RefRename { } /** + * Do the actual rename + * * @return the result of the rename operation. - * @throws IOException + * @throws java.io.IOException */ protected abstract Result doRename() throws IOException; /** + * Whether the {@code Constants#HEAD} reference needs to be linked to the + * new destination name. + * * @return true if the {@code Constants#HEAD} reference needs to be linked * to the new destination name. - * @throws IOException + * @throws java.io.IOException * the current value of {@code HEAD} cannot be read. */ protected boolean needToUpdateHEAD() throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefUpdate.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefUpdate.java index 766b21da0e..06a7576db1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefUpdate.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefUpdate.java @@ -233,10 +233,18 @@ public abstract class RefUpdate { refLogMessage = ""; //$NON-NLS-1$ } - /** @return the reference database this update modifies. */ + /** + * Get the reference database this update modifies. + * + * @return the reference database this update modifies. + */ protected abstract RefDatabase getRefDatabase(); - /** @return the repository storing the database's objects. */ + /** + * Get the repository storing the database's objects. + * + * @return the repository storing the database's objects. + */ protected abstract Repository getRepository(); /** @@ -251,33 +259,44 @@ public abstract class RefUpdate { * current reference. * @return true if the lock was acquired and the reference is likely * protected from concurrent modification; false if it failed. - * @throws IOException + * @throws java.io.IOException * the lock couldn't be taken due to an unexpected storage * failure, and not because of a concurrent update. */ protected abstract boolean tryLock(boolean deref) throws IOException; - /** Releases the lock taken by {@link #tryLock} if it succeeded. */ + /** + * Releases the lock taken by {@link #tryLock} if it succeeded. + */ protected abstract void unlock(); /** + * Do update + * * @param desiredResult + * a {@link org.eclipse.jgit.lib.RefUpdate.Result} object. * @return {@code result} - * @throws IOException + * @throws java.io.IOException */ protected abstract Result doUpdate(Result desiredResult) throws IOException; /** + * Do delete + * * @param desiredResult + * a {@link org.eclipse.jgit.lib.RefUpdate.Result} object. * @return {@code result} - * @throws IOException + * @throws java.io.IOException */ protected abstract Result doDelete(Result desiredResult) throws IOException; /** + * Do link + * * @param target - * @return {@link Result#NEW} on success. - * @throws IOException + * a {@link java.lang.String} object. + * @return {@link org.eclipse.jgit.lib.RefUpdate.Result#NEW} on success. + * @throws java.io.IOException */ protected abstract Result doLink(String target) throws IOException; @@ -290,7 +309,11 @@ public abstract class RefUpdate { return getRef().getName(); } - /** @return the reference this update will create or modify. */ + /** + * Get the reference this update will create or modify. + * + * @return the reference this update will create or modify. + */ public Ref getRef() { return ref; } @@ -332,21 +355,27 @@ public abstract class RefUpdate { } /** + * Get the expected value of the ref after the lock is taken, but before + * update occurs. + * * @return the expected value of the ref after the lock is taken, but before * update occurs. Null to avoid the compare and swap test. Use - * {@link ObjectId#zeroId()} to indicate expectation of a - * non-existant ref. + * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} to indicate + * expectation of a non-existant ref. */ public ObjectId getExpectedOldObjectId() { return expValue; } /** + * Set the expected value of the ref after the lock is taken, but before + * update occurs. + * * @param id * the expected value of the ref after the lock is taken, but * before update occurs. Null to avoid the compare and swap test. - * Use {@link ObjectId#zeroId()} to indicate expectation of a - * non-existant ref. + * Use {@link org.eclipse.jgit.lib.ObjectId#zeroId()} to indicate + * expectation of a non-existant ref. */ public void setExpectedOldObjectId(final AnyObjectId id) { expValue = id != null ? id.toObjectId() : null; @@ -371,7 +400,11 @@ public abstract class RefUpdate { force = b; } - /** @return identity of the user making the change in the reflog. */ + /** + * Get identity of the user making the change in the reflog. + * + * @return identity of the user making the change in the reflog. + */ public PersonIdent getRefLogIdent() { return refLogIdent; } @@ -402,7 +435,11 @@ public abstract class RefUpdate { return refLogMessage; } - /** @return {@code true} if the ref log message should show the result. */ + /** + * Whether the ref log message should show the result. + * + * @return {@code true} if the ref log message should show the result. + */ protected boolean isRefLogIncludingResult() { return refLogIncludeResult; } @@ -436,7 +473,9 @@ public abstract class RefUpdate { } } - /** Don't record this update in the ref's associated reflog. */ + /** + * Don't record this update in the ref's associated reflog. + */ public void disableRefLog() { refLogMessage = null; refLogIncludeResult = false; @@ -535,7 +574,7 @@ public abstract class RefUpdate { * the merge test is performed. * * @return the result status of the update. - * @throws IOException + * @throws java.io.IOException * an unexpected IO error occurred while writing changes. */ public Result forceUpdate() throws IOException { @@ -555,7 +594,7 @@ public abstract class RefUpdate { * * * @return the result status of the update. - * @throws IOException + * @throws java.io.IOException * an unexpected IO error occurred while writing changes. */ public Result update() throws IOException { @@ -573,7 +612,7 @@ public abstract class RefUpdate { * a RevWalk instance this update command can borrow to perform * the merge test. The walk will be reset to perform the test. * @return the result status of the update. - * @throws IOException + * @throws java.io.IOException * an unexpected IO error occurred while writing changes. */ public Result update(final RevWalk walk) throws IOException { @@ -603,7 +642,7 @@ public abstract class RefUpdate { * * * @return the result status of the delete. - * @throws IOException + * @throws java.io.IOException */ public Result delete() throws IOException { try (RevWalk rw = new RevWalk(getRepository())) { @@ -618,7 +657,7 @@ public abstract class RefUpdate { * a RevWalk instance this delete command can borrow to perform * the merge test. The walk will be reset to perform the test. * @return the result status of the delete. - * @throws IOException + * @throws java.io.IOException */ public Result delete(final RevWalk walk) throws IOException { final String myName = detachingSymbolicRef @@ -656,8 +695,9 @@ public abstract class RefUpdate { * @param target * name of the new target for this reference. The new target name * must be absolute, so it must begin with {@code refs/}. - * @return {@link Result#NEW} or {@link Result#FORCED} on success. - * @throws IOException + * @return {@link org.eclipse.jgit.lib.RefUpdate.Result#NEW} or + * {@link org.eclipse.jgit.lib.RefUpdate.Result#FORCED} on success. + * @throws java.io.IOException */ public Result link(String target) throws IOException { if (!target.startsWith(Constants.R_REFS)) @@ -751,6 +791,7 @@ public abstract class RefUpdate { * are checked explicitly. * * @param check + * whether to enable the check for conflicting ref names. * @since 3.0 */ public void setCheckConflicting(boolean check) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefWriter.java index 3a02b22813..90a0350dd7 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefWriter.java @@ -56,8 +56,8 @@ import org.eclipse.jgit.util.RefList; import org.eclipse.jgit.util.RefMap; /** - * Writes out refs to the {@link Constants#INFO_REFS} and - * {@link Constants#PACKED_REFS} files. + * Writes out refs to the {@link org.eclipse.jgit.lib.Constants#INFO_REFS} and + * {@link org.eclipse.jgit.lib.Constants#PACKED_REFS} files. * * This class is abstract as the writing of the files must be handled by the * caller. This is because it is used by transport classes as well. @@ -67,6 +67,8 @@ public abstract class RefWriter { private final Collection refs; /** + *

Constructor for RefWriter.

+ * * @param refs * the complete set of references. This should have been computed * by applying updates to the advertised refs already discovered. @@ -76,6 +78,8 @@ public abstract class RefWriter { } /** + *

Constructor for RefWriter.

+ * * @param refs * the complete set of references. This should have been computed * by applying updates to the advertised refs already discovered. @@ -88,6 +92,8 @@ public abstract class RefWriter { } /** + *

Constructor for RefWriter.

+ * * @param refs * the complete set of references. This should have been computed * by applying updates to the advertised refs already discovered. @@ -97,13 +103,13 @@ public abstract class RefWriter { } /** - * Rebuild the {@link Constants#INFO_REFS}. + * Rebuild the {@link org.eclipse.jgit.lib.Constants#INFO_REFS}. *

- * This method rebuilds the contents of the {@link Constants#INFO_REFS} file - * to match the passed list of references. - * + * This method rebuilds the contents of the + * {@link org.eclipse.jgit.lib.Constants#INFO_REFS} file to match the passed + * list of references. * - * @throws IOException + * @throws java.io.IOException * writing is not supported, or attempting to write the file * failed, possibly due to permissions or remote disk full, etc. */ @@ -142,13 +148,14 @@ public abstract class RefWriter { } /** - * Rebuild the {@link Constants#PACKED_REFS} file. + * Rebuild the {@link org.eclipse.jgit.lib.Constants#PACKED_REFS} file. *

- * This method rebuilds the contents of the {@link Constants#PACKED_REFS} - * file to match the passed list of references, including only those refs - * that have a storage type of {@link Ref.Storage#PACKED}. + * This method rebuilds the contents of the + * {@link org.eclipse.jgit.lib.Constants#PACKED_REFS} file to match the + * passed list of references, including only those refs that have a storage + * type of {@link org.eclipse.jgit.lib.Ref.Storage#PACKED}. * - * @throws IOException + * @throws java.io.IOException * writing is not supported, or attempting to write the file * failed, possibly due to permissions or remote disk full, etc. */ @@ -203,7 +210,7 @@ public abstract class RefWriter { * path to ref file. * @param content * byte content of file to be written. - * @throws IOException + * @throws java.io.IOException */ protected abstract void writeFile(String file, byte[] content) throws IOException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogEntry.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogEntry.java index afa6521d67..51f2ea0ab7 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogEntry.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogEntry.java @@ -83,28 +83,39 @@ public interface ReflogEntry { public static final String PREFIX_FORCED_UPDATE = "forced-update"; //$NON-NLS-1$ /** + * Get the commit id before the change + * * @return the commit id before the change */ public abstract ObjectId getOldId(); /** + * Get the commit id after the change + * * @return the commit id after the change */ public abstract ObjectId getNewId(); /** + * Get user performing the change + * * @return user performing the change */ public abstract PersonIdent getWho(); /** + * Get textual description of the change + * * @return textual description of the change */ public abstract String getComment(); /** - * @return a {@link CheckoutEntry} with parsed information about a branch - * switch, or null if the entry is not a checkout + * Parse checkout + * + * @return a {@link org.eclipse.jgit.lib.CheckoutEntry} with parsed + * information about a branch switch, or null if the entry is not a + * checkout */ public abstract CheckoutEntry parseCheckout(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogReader.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogReader.java index d3f25369bd..f97b07e08c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogReader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogReader.java @@ -57,13 +57,15 @@ public interface ReflogReader { * Get the last entry in the reflog * * @return the latest reflog entry, or null if no log - * @throws IOException + * @throws java.io.IOException */ public abstract ReflogEntry getLastEntry() throws IOException; /** + * Get all reflog entries in reverse order + * * @return all reflog entries in reverse order - * @throws IOException + * @throws java.io.IOException */ public abstract List getReverseEntries() throws IOException; @@ -71,17 +73,19 @@ public interface ReflogReader { * Get specific entry in the reflog relative to the last entry which is * considered entry zero. * - * @param number + * @param number a int. * @return reflog entry or null if not found - * @throws IOException + * @throws java.io.IOException */ public abstract ReflogEntry getReverseEntry(int number) throws IOException; /** + * Get all reflog entries in reverse order + * * @param max * max number of entries to read * @return all reflog entries in reverse order - * @throws IOException + * @throws java.io.IOException */ public abstract List getReverseEntries(int max) throws IOException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java index 72f79f4a9c..fda670bbb0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java @@ -83,7 +83,6 @@ import org.eclipse.jgit.events.IndexChangedListener; import org.eclipse.jgit.events.ListenerList; import org.eclipse.jgit.events.RepositoryEvent; import org.eclipse.jgit.internal.JGitText; -import org.eclipse.jgit.internal.storage.file.GC; import org.eclipse.jgit.revwalk.RevBlob; import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.revwalk.RevObject; @@ -106,9 +105,9 @@ import org.slf4j.LoggerFactory; * A repository holds all objects and refs used for managing source code (could * be any type of file, but source code is what SCM's are typically used for). *

- * The thread-safety of a {@link Repository} very much depends on the concrete - * implementation. Applications working with a generic {@code Repository} type - * must not assume the instance is thread-safe. + * The thread-safety of a {@link org.eclipse.jgit.lib.Repository} very much + * depends on the concrete implementation. Applications working with a generic + * {@code Repository} type must not assume the instance is thread-safe. *

    *
  • {@code FileRepository} is thread-safe. *
  • {@code DfsRepository} thread-safety is determined by its subclass. @@ -129,7 +128,11 @@ public abstract class Repository implements AutoCloseable { "(^|/)(aux|com[1-9]|con|lpt[1-9]|nul|prn)(\\.[^/]*)?", //$NON-NLS-1$ Pattern.CASE_INSENSITIVE); - /** @return the global listener list observing all events in this JVM. */ + /** + * Get the global listener list observing all events in this JVM. + * + * @return the global listener list observing all events in this JVM. + */ public static ListenerList getGlobalListenerList() { return globalListeners; } @@ -166,7 +169,11 @@ public abstract class Repository implements AutoCloseable { indexFile = options.getIndexFile(); } - /** @return listeners observing only events on this repository. */ + /** + * Get listeners observing only events on this repository. + * + * @return listeners observing only events on this repository. + */ @NonNull public ListenerList getListenerList() { return myListeners; @@ -193,7 +200,7 @@ public abstract class Repository implements AutoCloseable { * Repository with working tree is created using this method. This method is * the same as {@code create(false)}. * - * @throws IOException + * @throws java.io.IOException * @see #create(boolean) */ public void create() throws IOException { @@ -207,12 +214,14 @@ public abstract class Repository implements AutoCloseable { * @param bare * if true, a bare repository (a repository without a working * directory) is created. - * @throws IOException + * @throws java.io.IOException * in case of IO problem */ public abstract void create(boolean bare) throws IOException; /** + * Get local metadata directory + * * @return local metadata directory; {@code null} if repository isn't local. */ /* @@ -227,44 +236,64 @@ public abstract class Repository implements AutoCloseable { } /** + * Get the object database which stores this repository's data. + * * @return the object database which stores this repository's data. */ @NonNull public abstract ObjectDatabase getObjectDatabase(); - /** @return a new inserter to create objects in {@link #getObjectDatabase()} */ + /** + * Create a new inserter to create objects in {@link #getObjectDatabase()}. + * + * @return a new inserter to create objects in {@link #getObjectDatabase()}. + */ @NonNull public ObjectInserter newObjectInserter() { return getObjectDatabase().newInserter(); } - /** @return a new reader to read objects from {@link #getObjectDatabase()} */ + /** + * Create a new reader to read objects from {@link #getObjectDatabase()}. + * + * @return a new reader to read objects from {@link #getObjectDatabase()}. + */ @NonNull public ObjectReader newObjectReader() { return getObjectDatabase().newReader(); } - /** @return the reference database which stores the reference namespace. */ + /** + * Get the reference database which stores the reference namespace. + * + * @return the reference database which stores the reference namespace. + */ @NonNull public abstract RefDatabase getRefDatabase(); /** - * @return the configuration of this repository + * Get the configuration of this repository. + * + * @return the configuration of this repository. */ @NonNull public abstract StoredConfig getConfig(); /** - * @return a new {@link AttributesNodeProvider}. This - * {@link AttributesNodeProvider} is lazy loaded only once. It means - * that it will not be updated after loading. Prefer creating new - * instance for each use. + * Create a new {@link org.eclipse.jgit.attributes.AttributesNodeProvider}. + * + * @return a new {@link org.eclipse.jgit.attributes.AttributesNodeProvider}. + * This {@link org.eclipse.jgit.attributes.AttributesNodeProvider} + * is lazy loaded only once. It means that it will not be updated + * after loading. Prefer creating new instance for each use. * @since 4.2 */ @NonNull public abstract AttributesNodeProvider createAttributesNodeProvider(); /** + * Get the used file system abstraction. + * * @return the used file system abstraction, or or {@code null} if * repository isn't local. */ @@ -280,7 +309,11 @@ public abstract class Repository implements AutoCloseable { } /** + * Whether the specified object is stored in this repo or any of the known + * shared repositories. + * * @param objectId + * a {@link org.eclipse.jgit.lib.AnyObjectId} object. * @return true if the specified object is stored in this repo or any of the * known shared repositories. */ @@ -301,10 +334,11 @@ public abstract class Repository implements AutoCloseable { * * @param objectId * identity of the object to open. - * @return a {@link ObjectLoader} for accessing the object. - * @throws MissingObjectException + * @return a {@link org.eclipse.jgit.lib.ObjectLoader} for accessing the + * object. + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ @NonNull @@ -323,16 +357,17 @@ public abstract class Repository implements AutoCloseable { * identity of the object to open. * @param typeHint * hint about the type of object being requested, e.g. - * {@link Constants#OBJ_BLOB}; {@link ObjectReader#OBJ_ANY} if - * the object type is not known, or does not matter to the - * caller. - * @return a {@link ObjectLoader} for accessing the object. - * @throws MissingObjectException + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB}; + * {@link org.eclipse.jgit.lib.ObjectReader#OBJ_ANY} if the + * object type is not known, or does not matter to the caller. + * @return a {@link org.eclipse.jgit.lib.ObjectLoader} for accessing the + * object. + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * typeHint was not OBJ_ANY, and the object's actual type does * not match typeHint. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ @NonNull @@ -350,7 +385,7 @@ public abstract class Repository implements AutoCloseable { * @return an update command. The caller must finish populating this command * and then invoke one of the update methods to actually make a * change. - * @throws IOException + * @throws java.io.IOException * a symbolic ref was passed in and could not be resolved back * to the base ref, as the symbolic ref could not be read. */ @@ -369,7 +404,7 @@ public abstract class Repository implements AutoCloseable { * @return an update command. The caller must finish populating this command * and then invoke one of the update methods to actually make a * change. - * @throws IOException + * @throws java.io.IOException * a symbolic ref was passed in and could not be resolved back * to the base ref, as the symbolic ref could not be read. */ @@ -386,9 +421,8 @@ public abstract class Repository implements AutoCloseable { * @param toRef * name of ref to rename to * @return an update command that knows how to rename a branch to another. - * @throws IOException + * @throws java.io.IOException * the rename could not be performed. - * */ @NonNull public RefRename renameRef(final String fromRef, final String toRef) throws IOException { @@ -432,17 +466,17 @@ public abstract class Repository implements AutoCloseable { * A git object references expression * @return an ObjectId or {@code null} if revstr can't be resolved to any * ObjectId - * @throws AmbiguousObjectException + * @throws org.eclipse.jgit.errors.AmbiguousObjectException * {@code revstr} contains an abbreviated ObjectId and this * repository contains more than one object which match to the * input abbreviation. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the id parsed does not meet the type required to finish * applying the operators in the expression. - * @throws RevisionSyntaxException + * @throws org.eclipse.jgit.errors.RevisionSyntaxException * the expression is not supported by this implementation, or * does not meet the standard syntax. - * @throws IOException + * @throws java.io.IOException * on serious errors */ @Nullable @@ -466,11 +500,11 @@ public abstract class Repository implements AutoCloseable { * Thus this method can be used to process an expression to a method that * expects a branch or revision id. * - * @param revstr + * @param revstr a {@link java.lang.String} object. * @return object id or ref name from resolved expression or {@code null} if * given expression cannot be resolved - * @throws AmbiguousObjectException - * @throws IOException + * @throws org.eclipse.jgit.errors.AmbiguousObjectException + * @throws java.io.IOException */ @Nullable public String simplify(final String revstr) @@ -889,12 +923,18 @@ public abstract class Repository implements AutoCloseable { } } - /** Increment the use counter by one, requiring a matched {@link #close()}. */ + /** + * Increment the use counter by one, requiring a matched {@link #close()}. + */ public void incrementOpen() { useCnt.incrementAndGet(); } - /** Decrement the use count, and maybe close resources. */ + /** + * {@inheritDoc} + *

    + * Decrement the use count, and maybe close resources. + */ @Override public void close() { int newCount = useCnt.decrementAndGet(); @@ -930,6 +970,7 @@ public abstract class Repository implements AutoCloseable { getRefDatabase().close(); } + /** {@inheritDoc} */ @Override @NonNull public String toString() { @@ -959,7 +1000,7 @@ public abstract class Repository implements AutoCloseable { * an ObjectId in hex format if the current branch is detached, or * {@code null} if the repository is corrupt and has no HEAD * reference. - * @throws IOException + * @throws java.io.IOException */ @Nullable public String getFullBranch() throws IOException { @@ -987,7 +1028,7 @@ public abstract class Repository implements AutoCloseable { * @return name of current branch (for example {@code master}), an ObjectId * in hex format if the current branch is detached, or {@code null} * if the repository is corrupt and has no HEAD reference. - * @throws IOException + * @throws java.io.IOException */ @Nullable public String getBranch() throws IOException { @@ -1020,7 +1061,7 @@ public abstract class Repository implements AutoCloseable { * "master" which is is automatically expanded to * "refs/heads/master" if "refs/heads/master" already exists. * @return the Ref with the given name, or {@code null} if it does not exist - * @throws IOException + * @throws java.io.IOException * @deprecated Use {@link #exactRef(String)} or {@link #findRef(String)} * instead. */ @@ -1038,7 +1079,7 @@ public abstract class Repository implements AutoCloseable { * form; e.g., "master" is not automatically expanded to * "refs/heads/master". * @return the Ref with the given name, or {@code null} if it does not exist - * @throws IOException + * @throws java.io.IOException * @since 4.2 */ @Nullable @@ -1054,7 +1095,7 @@ public abstract class Repository implements AutoCloseable { * "master" which is is automatically expanded to * "refs/heads/master" if "refs/heads/master" already exists. * @return the Ref with the given name, or {@code null} if it does not exist - * @throws IOException + * @throws java.io.IOException * @since 4.2 */ @Nullable @@ -1063,6 +1104,8 @@ public abstract class Repository implements AutoCloseable { } /** + * Get mutable map of all known refs + * * @return mutable map of all known refs (heads, tags, remotes). */ @NonNull @@ -1075,6 +1118,8 @@ public abstract class Repository implements AutoCloseable { } /** + * Get mutable map of all tags + * * @return mutable map of all tags; key is short tag name ("v1.0") and value * of the entry contains the ref with the full tag name * ("refs/tags/v1.0"). @@ -1092,7 +1137,8 @@ public abstract class Repository implements AutoCloseable { * Peel a possibly unpeeled reference to an annotated tag. *

    * If the ref cannot be peeled (as it does not refer to an annotated tag) - * the peeled id stays null, but {@link Ref#isPeeled()} will be true. + * the peeled id stays null, but {@link org.eclipse.jgit.lib.Ref#isPeeled()} + * will be true. * * @param ref * The ref to peel @@ -1114,6 +1160,8 @@ public abstract class Repository implements AutoCloseable { } /** + * Get a map with all objects referenced by a peeled ref. + * * @return a map with all objects referenced by a peeled ref. */ @NonNull @@ -1141,9 +1189,11 @@ public abstract class Repository implements AutoCloseable { } /** + * Get the index file location or {@code null} if repository isn't local. + * * @return the index file location or {@code null} if repository isn't * local. - * @throws NoWorkTreeException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1163,11 +1213,11 @@ public abstract class Repository implements AutoCloseable { * @param id * name of the commit object. * @return reference to the commit object. Never null. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the supplied commit does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the supplied id is not a commit or an annotated tag. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. * @since 4.8 */ @@ -1190,12 +1240,12 @@ public abstract class Repository implements AutoCloseable { * * @return a cache representing the contents of the specified index file (if * it exists) or an empty cache if the file does not exist. - * @throws NoWorkTreeException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. - * @throws IOException + * @throws java.io.IOException * the index file is present but could not be read. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the index file is using a format or extension that this * library does not support. */ @@ -1214,13 +1264,13 @@ public abstract class Repository implements AutoCloseable { * * @return a cache representing the contents of the specified index file (if * it exists) or an empty cache if the file does not exist. - * @throws NoWorkTreeException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. - * @throws IOException + * @throws java.io.IOException * the index file is present but could not be read, or the lock * could not be obtained. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the index file is using a format or extension that this * library does not support. */ @@ -1239,7 +1289,9 @@ public abstract class Repository implements AutoCloseable { } /** - * @return an important state + * Get the repository state + * + * @return the repository state */ @NonNull public RepositoryState getRepositoryState() { @@ -1320,8 +1372,7 @@ public abstract class Repository implements AutoCloseable { * * For portability reasons '\' is excluded * - * @param refName - * + * @param refName a {@link java.lang.String} object. * @return true if refName is a valid ref name */ public static boolean isValidRefName(final String refName) { @@ -1392,7 +1443,6 @@ public abstract class Repository implements AutoCloseable { * * @param name * to normalize - * * @return The normalized name or an empty String if it is {@code null} or * empty. * @since 4.7 @@ -1499,6 +1549,8 @@ public abstract class Repository implements AutoCloseable { } /** + * Whether this repository is bare + * * @return true if this is bare, which implies it has no working directory. */ public boolean isBare() { @@ -1506,9 +1558,12 @@ public abstract class Repository implements AutoCloseable { } /** + * Get the root directory of the working tree, where files are checked out + * for viewing and editing. + * * @return the root directory of the working tree, where files are checked * out for viewing and editing. - * @throws NoWorkTreeException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1522,7 +1577,7 @@ public abstract class Repository implements AutoCloseable { /** * Force a scan for changed refs. * - * @throws IOException + * @throws java.io.IOException */ public abstract void scanForRepoChanges() throws IOException; @@ -1532,8 +1587,10 @@ public abstract class Repository implements AutoCloseable { public abstract void notifyIndexChanged(); /** - * @param refName + * Get a shortened more user friendly ref name * + * @param refName + * a {@link java.lang.String} object. * @return a more user friendly ref name */ @NonNull @@ -1548,7 +1605,10 @@ public abstract class Repository implements AutoCloseable { } /** + * Get a shortened more user friendly remote tracking branch name + * * @param refName + * a {@link java.lang.String} object. * @return the remote branch name part of refName, i.e. without * the refs/remotes/<remote> prefix, if * refName represents a remote tracking branch; @@ -1566,7 +1626,10 @@ public abstract class Repository implements AutoCloseable { } /** + * Get remote name + * * @param refName + * a {@link java.lang.String} object. * @return the remote name part of refName, i.e. without the * refs/remotes/<remote> prefix, if * refName represents a remote tracking branch; @@ -1587,7 +1650,7 @@ public abstract class Repository implements AutoCloseable { * Read the {@code GIT_DIR/description} file for gitweb. * * @return description text; null if no description has been configured. - * @throws IOException + * @throws java.io.IOException * description cannot be accessed. * @since 4.6 */ @@ -1601,7 +1664,7 @@ public abstract class Repository implements AutoCloseable { * * @param description * new description; null to clear the description. - * @throws IOException + * @throws java.io.IOException * description cannot be persisted. * @since 4.6 */ @@ -1611,10 +1674,13 @@ public abstract class Repository implements AutoCloseable { } /** + * Get the reflog reader + * * @param refName - * @return a {@link ReflogReader} for the supplied refname, or {@code null} - * if the named ref does not exist. - * @throws IOException + * a {@link java.lang.String} object. + * @return a {@link org.eclipse.jgit.lib.ReflogReader} for the supplied + * refname, or {@code null} if the named ref does not exist. + * @throws java.io.IOException * the ref could not be accessed. * @since 3.0 */ @@ -1629,8 +1695,8 @@ public abstract class Repository implements AutoCloseable { * * @return a String containing the content of the MERGE_MSG file or * {@code null} if this file doesn't exist - * @throws IOException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1648,8 +1714,7 @@ public abstract class Repository implements AutoCloseable { * @param msg * the message which should be written or null to * delete the file - * - * @throws IOException + * @throws java.io.IOException */ public void writeMergeCommitMsg(String msg) throws IOException { File mergeMsgFile = new File(gitDir, Constants.MERGE_MSG); @@ -1663,8 +1728,8 @@ public abstract class Repository implements AutoCloseable { * * @return a String containing the content of the COMMIT_EDITMSG file or * {@code null} if this file doesn't exist - * @throws IOException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. * @since 4.0 @@ -1682,8 +1747,7 @@ public abstract class Repository implements AutoCloseable { * @param msg * the message which should be written or {@code null} to delete * the file - * - * @throws IOException + * @throws java.io.IOException * @since 4.0 */ public void writeCommitEditMsg(String msg) throws IOException { @@ -1699,8 +1763,8 @@ public abstract class Repository implements AutoCloseable { * @return a list of commits which IDs are listed in the MERGE_HEAD file or * {@code null} if this file doesn't exist. Also if the file exists * but is empty {@code null} will be returned - * @throws IOException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1731,7 +1795,7 @@ public abstract class Repository implements AutoCloseable { * @param heads * a list of commits which IDs should be written to * $GIT_DIR/MERGE_HEAD or null to delete the file - * @throws IOException + * @throws java.io.IOException */ public void writeMergeHeads(List heads) throws IOException { writeHeadsFile(heads, Constants.MERGE_HEAD); @@ -1743,8 +1807,8 @@ public abstract class Repository implements AutoCloseable { * @return object id from CHERRY_PICK_HEAD file or {@code null} if this file * doesn't exist. Also if the file exists but is empty {@code null} * will be returned - * @throws IOException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1767,8 +1831,8 @@ public abstract class Repository implements AutoCloseable { * @return object id from REVERT_HEAD file or {@code null} if this file * doesn't exist. Also if the file exists but is empty {@code null} * will be returned - * @throws IOException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1790,7 +1854,7 @@ public abstract class Repository implements AutoCloseable { * @param head * an object id of the cherry commit or null to * delete the file - * @throws IOException + * @throws java.io.IOException */ public void writeCherryPickHead(ObjectId head) throws IOException { List heads = (head != null) ? Collections.singletonList(head) @@ -1805,7 +1869,7 @@ public abstract class Repository implements AutoCloseable { * @param head * an object id of the revert commit or null to * delete the file - * @throws IOException + * @throws java.io.IOException */ public void writeRevertHead(ObjectId head) throws IOException { List heads = (head != null) ? Collections.singletonList(head) @@ -1819,7 +1883,7 @@ public abstract class Repository implements AutoCloseable { * @param head * an object id of the original HEAD commit or null * to delete the file - * @throws IOException + * @throws java.io.IOException */ public void writeOrigHead(ObjectId head) throws IOException { List heads = head != null ? Collections.singletonList(head) @@ -1833,8 +1897,8 @@ public abstract class Repository implements AutoCloseable { * @return object id from ORIG_HEAD file or {@code null} if this file * doesn't exist. Also if the file exists but is empty {@code null} * will be returned - * @throws IOException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1854,7 +1918,7 @@ public abstract class Repository implements AutoCloseable { * * @return a String containing the content of the SQUASH_MSG file or * {@code null} if this file doesn't exist - * @throws IOException + * @throws java.io.IOException * @throws NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. @@ -1873,8 +1937,7 @@ public abstract class Repository implements AutoCloseable { * @param msg * the message which should be written or null to * delete the file - * - * @throws IOException + * @throws java.io.IOException */ public void writeSquashCommitMsg(String msg) throws IOException { File squashMsgFile = new File(gitDir, Constants.SQUASH_MSG); @@ -1970,7 +2033,7 @@ public abstract class Repository implements AutoCloseable { * @param includeComments * true if also comments should be reported * @return the list of steps - * @throws IOException + * @throws java.io.IOException * @since 3.2 */ @NonNull @@ -1990,7 +2053,7 @@ public abstract class Repository implements AutoCloseable { * the steps to be written * @param append * whether to append to an existing file or to write a new file - * @throws IOException + * @throws java.io.IOException * @since 3.2 */ public void writeRebaseTodoFile(String path, List steps, @@ -2000,6 +2063,8 @@ public abstract class Repository implements AutoCloseable { } /** + * Get the names of all known remotes + * * @return the names of all known remotes * @since 3.4 */ @@ -2016,7 +2081,8 @@ public abstract class Repository implements AutoCloseable { * objects. *

    * Currently this option is supported for repositories of type - * {@code FileRepository} only. See {@link GC#setAuto(boolean)} for + * {@code FileRepository} only. See + * {@link org.eclipse.jgit.internal.storage.file.GC#setAuto(boolean)} for * configuration details. * * @param monitor diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryBuilder.java index 95be2d1f0d..65196a8083 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryBuilder.java @@ -46,7 +46,7 @@ package org.eclipse.jgit.lib; import java.io.File; /** - * Base class to support constructing a {@link Repository}. + * Base class to support constructing a {@link org.eclipse.jgit.lib.Repository}. *

    * Applications must set one of {@link #setGitDir(File)} or * {@link #setWorkTree(File)}, or use {@link #readEnvironment()} or diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCache.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCache.java index efbbfbce27..ce7ce8cd87 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCache.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCache.java @@ -62,7 +62,9 @@ import org.eclipse.jgit.util.RawParseUtils; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -/** Cache of active {@link Repository} instances. */ +/** + * Cache of active {@link org.eclipse.jgit.lib.Repository} instances. + */ public class RepositoryCache { private final static Logger LOG = LoggerFactory .getLogger(RepositoryCache.class); @@ -73,15 +75,17 @@ public class RepositoryCache { * Open an existing repository, reusing a cached instance if possible. *

    * When done with the repository, the caller must call - * {@link Repository#close()} to decrement the repository's usage counter. + * {@link org.eclipse.jgit.lib.Repository#close()} to decrement the + * repository's usage counter. * * @param location - * where the local repository is. Typically a {@link FileKey}. + * where the local repository is. Typically a + * {@link org.eclipse.jgit.lib.RepositoryCache.FileKey}. * @return the repository instance requested; caller must close when done. - * @throws IOException + * @throws java.io.IOException * the repository could not be read (likely its core.version * property is not supported). - * @throws RepositoryNotFoundException + * @throws org.eclipse.jgit.errors.RepositoryNotFoundException * there is no repository at the given location. */ public static Repository open(final Key location) throws IOException, @@ -93,16 +97,18 @@ public class RepositoryCache { * Open a repository, reusing a cached instance if possible. *

    * When done with the repository, the caller must call - * {@link Repository#close()} to decrement the repository's usage counter. + * {@link org.eclipse.jgit.lib.Repository#close()} to decrement the + * repository's usage counter. * * @param location - * where the local repository is. Typically a {@link FileKey}. + * where the local repository is. Typically a + * {@link org.eclipse.jgit.lib.RepositoryCache.FileKey}. * @param mustExist * If true, and the repository is not found, throws {@code * RepositoryNotFoundException}. If false, a repository instance * is created and registered anyway. * @return the repository instance requested; caller must close when done. - * @throws IOException + * @throws java.io.IOException * the repository could not be read (likely its core.version * property is not supported). * @throws RepositoryNotFoundException @@ -118,9 +124,10 @@ public class RepositoryCache { * Register one repository into the cache. *

    * During registration the cache automatically increments the usage counter, - * permitting it to retain the reference. A {@link FileKey} for the - * repository's {@link Repository#getDirectory()} is used to index the - * repository in the cache. + * permitting it to retain the reference. A + * {@link org.eclipse.jgit.lib.RepositoryCache.FileKey} for the repository's + * {@link org.eclipse.jgit.lib.Repository#getDirectory()} is used to index + * the repository in the cache. *

    * If another repository already is registered in the cache at this * location, the other instance is closed. @@ -156,8 +163,8 @@ public class RepositoryCache { *

    * Removes a repository from the cache, if it is still registered here. This * method will not close the repository, only remove it from the cache. See - * {@link RepositoryCache#close(Repository)} to remove and close the - * repository. + * {@link org.eclipse.jgit.lib.RepositoryCache#close(Repository)} to remove + * and close the repository. * * @param db * repository to unregister. @@ -174,8 +181,8 @@ public class RepositoryCache { *

    * Removes a repository from the cache, if it is still registered here. This * method will not close the repository, only remove it from the cache. See - * {@link RepositoryCache#close(Repository)} to remove and close the - * repository. + * {@link org.eclipse.jgit.lib.RepositoryCache#close(Repository)} to remove + * and close the repository. * * @param location * location of the repository to remove. @@ -186,6 +193,8 @@ public class RepositoryCache { } /** + * Get the locations of all repositories registered in the cache. + * * @return the locations of all repositories registered in the cache. * @since 4.1 */ @@ -202,7 +211,9 @@ public class RepositoryCache { return cache.cacheMap.get(key) == repo; } - /** Unregister all repositories from the cache. */ + /** + * Unregister all repositories from the cache. + */ public static void clear() { cache.clearAll(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCacheConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCacheConfig.java index 28cdaae443..3680dee4ef 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCacheConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCacheConfig.java @@ -68,23 +68,32 @@ public class RepositoryCacheConfig { private long cleanupDelayMillis; - /** Create a default configuration. */ + /** + * Create a default configuration. + */ public RepositoryCacheConfig() { expireAfterMillis = TimeUnit.HOURS.toMillis(1); cleanupDelayMillis = AUTO_CLEANUP_DELAY; } /** - * @return the time an unused repository should expired and be evicted from - * the RepositoryCache in milliseconds. Default is 1 hour. + * Get the time an unused repository should be expired and be evicted from + * the RepositoryCache in milliseconds. + * + * @return the time an unused repository should be expired and be evicted + * from the RepositoryCache in milliseconds. Default is 1 + * hour. */ public long getExpireAfter() { return expireAfterMillis; } /** + * Set the time an unused repository should be expired and be evicted from + * the RepositoryCache in milliseconds. + * * @param expireAfterMillis - * the time an unused repository should expired and be evicted + * the time an unused repository should be expired and be evicted * from the RepositoryCache in milliseconds. */ public void setExpireAfter(long expireAfterMillis) { @@ -92,6 +101,9 @@ public class RepositoryCacheConfig { } /** + * Get the delay between the periodic cleanup of expired repository in + * milliseconds. + * * @return the delay between the periodic cleanup of expired repository in * milliseconds. Default is minimum of 1/10 of expireAfterMillis * and 10 minutes @@ -105,6 +117,9 @@ public class RepositoryCacheConfig { } /** + * Set the delay between the periodic cleanup of expired repository in + * milliseconds. + * * @param cleanupDelayMillis * the delay between the periodic cleanup of expired repository * in milliseconds. Set it to {@link #AUTO_CLEANUP_DELAY} to diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryState.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryState.java index 9b7234b3af..c5d81b3d25 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryState.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryState.java @@ -381,7 +381,9 @@ public enum RepositoryState { }; /** - * @return true if changing HEAD is sane. + * Whether checkout can be done. + * + * @return whether checkout can be done. */ public abstract boolean canCheckout(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/StoredConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/StoredConfig.java index 344d520680..42ab891990 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/StoredConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/StoredConfig.java @@ -51,7 +51,9 @@ import org.eclipse.jgit.errors.ConfigInvalidException; * Persistent configuration that can be stored and loaded from a location. */ public abstract class StoredConfig extends Config { - /** Create a configuration with no default fallback. */ + /** + * Create a configuration with no default fallback. + */ public StoredConfig() { super(); } @@ -73,9 +75,9 @@ public abstract class StoredConfig extends Config { * If the configuration does not exist, this configuration is cleared, and * thus behaves the same as though the backing store exists, but is empty. * - * @throws IOException + * @throws java.io.IOException * the configuration could not be read (but does exist). - * @throws ConfigInvalidException + * @throws org.eclipse.jgit.errors.ConfigInvalidException * the configuration is not properly formatted. */ public abstract void load() throws IOException, ConfigInvalidException; @@ -83,11 +85,12 @@ public abstract class StoredConfig extends Config { /** * Save the configuration to the persistent store. * - * @throws IOException + * @throws java.io.IOException * the configuration could not be written. */ public abstract void save() throws IOException; + /** {@inheritDoc} */ @Override public void clear() { super.clear(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/SymbolicRef.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/SymbolicRef.java index 71d5cd7ac1..d4b83b0128 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/SymbolicRef.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/SymbolicRef.java @@ -47,7 +47,8 @@ import org.eclipse.jgit.annotations.NonNull; import org.eclipse.jgit.annotations.Nullable; /** - * A reference that indirectly points at another {@link Ref}. + * A reference that indirectly points at another + * {@link org.eclipse.jgit.lib.Ref}. *

    * A symbolic reference always derives its current value from the target * reference. @@ -70,17 +71,20 @@ public class SymbolicRef implements Ref { this.target = target; } + /** {@inheritDoc} */ @Override @NonNull public String getName() { return name; } + /** {@inheritDoc} */ @Override public boolean isSymbolic() { return true; } + /** {@inheritDoc} */ @Override @NonNull public Ref getLeaf() { @@ -90,35 +94,41 @@ public class SymbolicRef implements Ref { return dst; } + /** {@inheritDoc} */ @Override @NonNull public Ref getTarget() { return target; } + /** {@inheritDoc} */ @Override @Nullable public ObjectId getObjectId() { return getLeaf().getObjectId(); } + /** {@inheritDoc} */ @Override @NonNull public Storage getStorage() { return Storage.LOOSE; } + /** {@inheritDoc} */ @Override @Nullable public ObjectId getPeeledObjectId() { return getLeaf().getPeeledObjectId(); } + /** {@inheritDoc} */ @Override public boolean isPeeled() { return getLeaf().isPeeled(); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TagBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TagBuilder.java index 3490a5bc99..90ef5c779f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TagBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TagBuilder.java @@ -72,12 +72,20 @@ public class TagBuilder { private String message; - /** @return the type of object this tag refers to. */ + /** + * Get the type of object this tag refers to. + * + * @return the type of object this tag refers to. + */ public int getObjectType() { return type; } - /** @return the object this tag refers to. */ + /** + * Get the object this tag refers to. + * + * @return the object this tag refers to. + */ public ObjectId getObjectId() { return object; } @@ -105,7 +113,11 @@ public class TagBuilder { setObjectId(obj, obj.getType()); } - /** @return short name of the tag (no {@code refs/tags/} prefix). */ + /** + * Get short name of the tag (no {@code refs/tags/} prefix). + * + * @return short name of the tag (no {@code refs/tags/} prefix). + */ public String getTag() { return tag; } @@ -122,7 +134,11 @@ public class TagBuilder { this.tag = shortName; } - /** @return creator of this tag. May be null. */ + /** + * Get creator of this tag. + * + * @return creator of this tag. May be null. + */ public PersonIdent getTagger() { return tagger; } @@ -137,7 +153,11 @@ public class TagBuilder { tagger = taggerIdent; } - /** @return the complete commit message. */ + /** + * Get the complete commit message. + * + * @return the complete commit message. + */ public String getMessage() { return message; } @@ -203,6 +223,7 @@ public class TagBuilder { return build(); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TextProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TextProgressMonitor.java index c31c3c6939..936ce3dcc8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TextProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TextProgressMonitor.java @@ -51,13 +51,17 @@ import java.io.OutputStreamWriter; import java.io.PrintWriter; import java.io.Writer; -/** A simple progress reporter printing on a stream. */ +/** + * A simple progress reporter printing on a stream. + */ public class TextProgressMonitor extends BatchingProgressMonitor { private final Writer out; private boolean write; - /** Initialize a new progress monitor. */ + /** + * Initialize a new progress monitor. + */ public TextProgressMonitor() { this(new PrintWriter(new OutputStreamWriter(System.err, UTF_8))); } @@ -73,6 +77,7 @@ public class TextProgressMonitor extends BatchingProgressMonitor { this.write = true; } + /** {@inheritDoc} */ @Override protected void onUpdate(String taskName, int workCurr) { StringBuilder s = new StringBuilder(); @@ -80,6 +85,7 @@ public class TextProgressMonitor extends BatchingProgressMonitor { send(s); } + /** {@inheritDoc} */ @Override protected void onEndTask(String taskName, int workCurr) { StringBuilder s = new StringBuilder(); @@ -97,6 +103,7 @@ public class TextProgressMonitor extends BatchingProgressMonitor { s.append(workCurr); } + /** {@inheritDoc} */ @Override protected void onUpdate(String taskName, int cmp, int totalWork, int pcnt) { StringBuilder s = new StringBuilder(); @@ -104,6 +111,7 @@ public class TextProgressMonitor extends BatchingProgressMonitor { send(s); } + /** {@inheritDoc} */ @Override protected void onEndTask(String taskName, int cmp, int totalWork, int pcnt) { StringBuilder s = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ThreadSafeProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ThreadSafeProgressMonitor.java index 5824a55ff1..7e7d45dbf3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ThreadSafeProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ThreadSafeProgressMonitor.java @@ -48,7 +48,8 @@ import java.util.concurrent.atomic.AtomicInteger; import java.util.concurrent.locks.ReentrantLock; /** - * Wrapper around the general {@link ProgressMonitor} to make it thread safe. + * Wrapper around the general {@link org.eclipse.jgit.lib.ProgressMonitor} to + * make it thread safe. * * Updates to the underlying ProgressMonitor are made only from the thread that * allocated this wrapper. Callers are responsible for ensuring the allocating @@ -87,6 +88,7 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { this.process = new Semaphore(0); } + /** {@inheritDoc} */ @Override public void start(int totalTasks) { if (!isMainThread()) @@ -94,6 +96,7 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { pm.start(totalTasks); } + /** {@inheritDoc} */ @Override public void beginTask(String title, int totalWork) { if (!isMainThread()) @@ -101,7 +104,9 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { pm.beginTask(title, totalWork); } - /** Notify the monitor a worker is starting. */ + /** + * Notify the monitor a worker is starting. + */ public void startWorker() { startWorkers(1); } @@ -116,7 +121,9 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { workers.addAndGet(count); } - /** Notify the monitor a worker is finished. */ + /** + * Notify the monitor a worker is finished. + */ public void endWorker() { if (workers.decrementAndGet() == 0) process.release(); @@ -139,7 +146,7 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { * This method can only be invoked by the same thread that allocated this * ThreadSafeProgressMonior. * - * @throws InterruptedException + * @throws java.lang.InterruptedException * if the main thread is interrupted while waiting for * completion of workers. */ @@ -158,12 +165,14 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { pm.update(cnt); } + /** {@inheritDoc} */ @Override public void update(int completed) { if (0 == pendingUpdates.getAndAdd(completed)) process.release(); } + /** {@inheritDoc} */ @Override public boolean isCancelled() { lock.lock(); @@ -174,6 +183,7 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { } } + /** {@inheritDoc} */ @Override public void endTask() { if (!isMainThread()) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeFormatter.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeFormatter.java index 777ce94aa0..0d78d5900c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeFormatter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeFormatter.java @@ -94,7 +94,9 @@ public class TreeFormatter { private TemporaryBuffer.Heap overflowBuffer; - /** Create an empty formatter with a default buffer size. */ + /** + * Create an empty formatter with a default buffer size. + */ public TreeFormatter() { this(8192); } @@ -112,7 +114,7 @@ public class TreeFormatter { } /** - * Add a link to a submodule commit, mode is {@link FileMode#GITLINK}. + * Add a link to a submodule commit, mode is {@link org.eclipse.jgit.lib.FileMode#GITLINK}. * * @param name * name of the entry. @@ -124,7 +126,7 @@ public class TreeFormatter { } /** - * Add a subtree, mode is {@link FileMode#TREE}. + * Add a subtree, mode is {@link org.eclipse.jgit.lib.FileMode#TREE}. * * @param name * name of the entry. @@ -136,7 +138,7 @@ public class TreeFormatter { } /** - * Add a regular file, mode is {@link FileMode#REGULAR_FILE}. + * Add a regular file, mode is {@link org.eclipse.jgit.lib.FileMode#REGULAR_FILE}. * * @param name * name of the entry. @@ -307,7 +309,7 @@ public class TreeFormatter { * @param ins * the inserter to store the tree. * @return computed ObjectId of the tree - * @throws IOException + * @throws java.io.IOException * the tree could not be stored. */ public ObjectId insertTo(ObjectInserter ins) throws IOException { @@ -321,7 +323,7 @@ public class TreeFormatter { /** * Compute the ObjectId for this tree * - * @param ins + * @param ins a {@link org.eclipse.jgit.lib.ObjectInserter} object. * @return ObjectId for this tree */ public ObjectId computeId(ObjectInserter ins) { @@ -343,7 +345,8 @@ public class TreeFormatter { * This method is not efficient, as it needs to create a copy of the * internal buffer in order to supply an array of the correct size to the * caller. If the buffer is just to pass to an ObjectInserter, consider - * using {@link ObjectInserter#insert(TreeFormatter)} instead. + * using {@link org.eclipse.jgit.lib.ObjectInserter#insert(TreeFormatter)} + * instead. * * @return a copy of this formatter's buffer. */ @@ -362,6 +365,7 @@ public class TreeFormatter { } } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TypedConfigGetter.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TypedConfigGetter.java index 594edef665..aca2ad2eb8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TypedConfigGetter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TypedConfigGetter.java @@ -50,15 +50,15 @@ import org.eclipse.jgit.annotations.NonNull; import org.eclipse.jgit.transport.RefSpec; /** - * Something that knows how to convert plain strings from a git {@link Config} - * to typed values. + * Something that knows how to convert plain strings from a git + * {@link org.eclipse.jgit.lib.Config} to typed values. * * @since 4.9 */ public interface TypedConfigGetter { /** - * Get a boolean value from a git {@link Config}. + * Get a boolean value from a git {@link org.eclipse.jgit.lib.Config}. * * @param config * to get the value from @@ -77,10 +77,8 @@ public interface TypedConfigGetter { String name, boolean defaultValue); /** - * Parse an enumeration from a git {@link Config}. + * Parse an enumeration from a git {@link org.eclipse.jgit.lib.Config}. * - * @param - * type of the enumeration object. * @param config * to get the value from * @param all @@ -100,7 +98,7 @@ public interface TypedConfigGetter { String subsection, String name, T defaultValue); /** - * Obtain an integer value from a git {@link Config}. + * Obtain an integer value from a git {@link org.eclipse.jgit.lib.Config}. * * @param config * to get the value from @@ -118,7 +116,7 @@ public interface TypedConfigGetter { int defaultValue); /** - * Obtain a long value from a git {@link Config}. + * Obtain a long value from a git {@link org.eclipse.jgit.lib.Config}. * * @param config * to get the value from @@ -137,7 +135,7 @@ public interface TypedConfigGetter { /** * Parse a numerical time unit, such as "1 minute", from a git - * {@link Config}. + * {@link org.eclipse.jgit.lib.Config}. * * @param config * to get the value from @@ -161,7 +159,8 @@ public interface TypedConfigGetter { /** - * Parse a list of {@link RefSpec}s from a git {@link Config}. + * Parse a list of {@link org.eclipse.jgit.transport.RefSpec}s from a git + * {@link org.eclipse.jgit.lib.Config}. * * @param config * to get the list from @@ -171,7 +170,8 @@ public interface TypedConfigGetter { * subsection the key is in, or null if not in a subsection. * @param name * the key name. - * @return a possibly empty list of {@link RefSpec}s + * @return a possibly empty list of + * {@link org.eclipse.jgit.transport.RefSpec}s */ @NonNull List getRefSpecs(Config config, String section, String subsection, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/UserConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/UserConfig.java index 102a4518f6..1a3c6f6bd5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/UserConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/UserConfig.java @@ -48,7 +48,9 @@ package org.eclipse.jgit.lib; import org.eclipse.jgit.lib.Config.SectionParser; import org.eclipse.jgit.util.SystemReader; -/** The standard "user" configuration parameters. */ +/** + * The standard "user" configuration parameters. + */ public class UserConfig { /** Key for {@link Config#get(SectionParser)}. */ public static final Config.SectionParser KEY = UserConfig::new; @@ -94,6 +96,8 @@ public class UserConfig { } /** + * Get the author name as defined in the git variables and configurations. + * * @return the author name as defined in the git variables and * configurations. If no name could be found, try to use the system * user name instead. @@ -103,6 +107,9 @@ public class UserConfig { } /** + * Get the committer name as defined in the git variables and + * configurations. + * * @return the committer name as defined in the git variables and * configurations. If no name could be found, try to use the system * user name instead. @@ -112,26 +119,31 @@ public class UserConfig { } /** - * @return the author email as defined in git variables and - * configurations. If no email could be found, try to - * propose one default with the user name and the - * host name. + * Get the author email as defined in git variables and configurations. + * + * @return the author email as defined in git variables and configurations. + * If no email could be found, try to propose one default with the + * user name and the host name. */ public String getAuthorEmail() { return authorEmail; } /** + * Get the committer email as defined in git variables and configurations. + * * @return the committer email as defined in git variables and - * configurations. If no email could be found, try to - * propose one default with the user name and the - * host name. + * configurations. If no email could be found, try to propose one + * default with the user name and the host name. */ public String getCommitterEmail() { return committerEmail; } /** + * Whether the author name was not explicitly configured but constructed + * from information the system has about the logged on user + * * @return true if the author name was not explicitly configured but * constructed from information the system has about the logged on * user @@ -141,6 +153,9 @@ public class UserConfig { } /** + * Whether the author email was not explicitly configured but constructed + * from information the system has about the logged on user + * * @return true if the author email was not explicitly configured but * constructed from information the system has about the logged on * user @@ -150,6 +165,9 @@ public class UserConfig { } /** + * Whether the committer name was not explicitly configured but constructed + * from information the system has about the logged on user + * * @return true if the committer name was not explicitly configured but * constructed from information the system has about the logged on * user @@ -159,6 +177,9 @@ public class UserConfig { } /** + * Whether the author email was not explicitly configured but constructed + * from information the system has about the logged on user + * * @return true if the author email was not explicitly configured but * constructed from information the system has about the logged on * user diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/internal/WorkQueue.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/internal/WorkQueue.java index 3303f47722..e3f65ae7ba 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/internal/WorkQueue.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/internal/WorkQueue.java @@ -95,6 +95,8 @@ public class WorkQueue { } /** + * Get the WorkQueue's executor + * * @return the WorkQueue's executor */ public static ScheduledThreadPoolExecutor getExecutor() { -- 2.39.5