From fdbaa25db9a0c9c5190d96388734e7cc3e6a1e75 Mon Sep 17 00:00:00 2001 From: Matthias Sohn Date: Tue, 19 Dec 2017 23:06:46 +0100 Subject: [PATCH] Fix javadoc in org.eclipse.jgit util packages Change-Id: Ia655f45153bcf1d422ffffce6dcf914847e14c4c Signed-off-by: Matthias Sohn --- .../src/org/eclipse/jgit/util/Base64.java | 9 +- .../src/org/eclipse/jgit/util/BlockList.java | 12 +- .../jgit/util/CachedAuthenticator.java | 5 +- .../org/eclipse/jgit/util/ChangeIdUtil.java | 24 ++- .../src/org/eclipse/jgit/util/FS.java | 114 ++++++++---- .../src/org/eclipse/jgit/util/FS_POSIX.java | 39 ++-- .../src/org/eclipse/jgit/util/FS_Win32.java | 14 +- .../eclipse/jgit/util/FS_Win32_Cygwin.java | 18 +- .../src/org/eclipse/jgit/util/FileUtil.java | 120 ++++++++++--- .../src/org/eclipse/jgit/util/FileUtils.java | 170 +++++++++++------- .../eclipse/jgit/util/GitDateFormatter.java | 6 +- .../org/eclipse/jgit/util/GitDateParser.java | 38 ++-- .../src/org/eclipse/jgit/util/Holder.java | 14 +- .../org/eclipse/jgit/util/HttpSupport.java | 22 ++- .../src/org/eclipse/jgit/util/IO.java | 24 +-- .../src/org/eclipse/jgit/util/IntList.java | 23 ++- .../src/org/eclipse/jgit/util/LongList.java | 27 ++- .../src/org/eclipse/jgit/util/LongMap.java | 14 +- .../org/eclipse/jgit/util/MutableInteger.java | 4 +- .../src/org/eclipse/jgit/util/NB.java | 4 +- .../org/eclipse/jgit/util/ProcessResult.java | 8 + .../org/eclipse/jgit/util/QuotedString.java | 4 +- .../eclipse/jgit/util/RawCharSequence.java | 4 + .../org/eclipse/jgit/util/RawParseUtils.java | 24 +-- .../jgit/util/RawSubStringPattern.java | 1 + .../src/org/eclipse/jgit/util/RefList.java | 24 ++- .../src/org/eclipse/jgit/util/RefMap.java | 23 ++- .../jgit/util/RelativeDateFormatter.java | 10 +- .../org/eclipse/jgit/util/StringUtils.java | 18 +- .../org/eclipse/jgit/util/SystemReader.java | 53 ++++-- .../eclipse/jgit/util/TemporaryBuffer.java | 31 ++-- .../jgit/util/io/AutoCRLFInputStream.java | 3 + .../jgit/util/io/AutoCRLFOutputStream.java | 13 +- .../jgit/util/io/AutoLFInputStream.java | 7 +- .../jgit/util/io/AutoLFOutputStream.java | 15 ++ .../jgit/util/io/CountingOutputStream.java | 14 +- .../jgit/util/io/DisabledOutputStream.java | 5 +- .../util/io/EolCanonicalizingInputStream.java | 2 +- .../jgit/util/io/EolStreamTypeUtil.java | 36 ++-- .../eclipse/jgit/util/io/InterruptTimer.java | 12 +- .../jgit/util/io/IsolatedOutputStream.java | 4 + .../jgit/util/io/LimitedInputStream.java | 27 +-- .../eclipse/jgit/util/io/MessageWriter.java | 16 +- .../jgit/util/io/NullOutputStream.java | 3 + .../util/io/SafeBufferedOutputStream.java | 6 + .../jgit/util/io/StreamCopyThread.java | 7 +- .../eclipse/jgit/util/io/TeeInputStream.java | 16 +- .../jgit/util/io/ThrowingPrintWriter.java | 35 ++-- .../jgit/util/io/TimeoutInputStream.java | 16 +- .../jgit/util/io/TimeoutOutputStream.java | 20 ++- .../jgit/util/io/UnionInputStream.java | 11 +- .../src/org/eclipse/jgit/util/sha1/SHA1.java | 19 +- .../util/sha1/Sha1CollisionException.java | 3 +- .../jgit/util/time/MonotonicClock.java | 16 +- .../jgit/util/time/MonotonicSystemClock.java | 4 +- .../jgit/util/time/ProposedTimestamp.java | 51 ++++-- 56 files changed, 876 insertions(+), 386 deletions(-) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/Base64.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/Base64.java index 7f897982c2..0c27ced76b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/Base64.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/Base64.java @@ -19,14 +19,13 @@ import org.eclipse.jgit.internal.JGitText; *

* I am placing this code in the Public Domain. Do with it as you will. This * software comes with no guarantees or warranties but with plenty of - * well-wishing instead! Please visit http://iharder.net/base64 periodically - * to check for updates or to contribute improvements. + * well-wishing instead! Please visit + * http://iharder.net/base64 + * periodically to check for updates or to contribute improvements. *

* * @author Robert Harder * @author rob@iharder.net - * @version 2.1, stripped to minimum feature set used by JGit. */ public class Base64 { /** The equals sign (=) as a byte. */ @@ -248,7 +247,7 @@ public class Base64 { * @param len * The length of characters to decode * @return decoded data - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the input is not a valid Base64 sequence. */ public static byte[] decode(byte[] source, int off, int len) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/BlockList.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/BlockList.java index c86c588acd..c3d474720f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/BlockList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/BlockList.java @@ -84,7 +84,9 @@ public class BlockList extends AbstractList { private T[] tailBlock; - /** Initialize an empty list. */ + /** + * Initialize an empty list. + */ public BlockList() { directory = BlockList. newDirectory(256); directory[0] = BlockList. newBlock(); @@ -106,11 +108,13 @@ public class BlockList extends AbstractList { tailBlock = directory[0]; } + /** {@inheritDoc} */ @Override public int size() { return size; } + /** {@inheritDoc} */ @Override public void clear() { for (T[] block : directory) { @@ -123,6 +127,7 @@ public class BlockList extends AbstractList { tailBlock = directory[0]; } + /** {@inheritDoc} */ @Override public T get(int index) { if (index < 0 || size <= index) @@ -130,6 +135,7 @@ public class BlockList extends AbstractList { return directory[toDirectoryIndex(index)][toBlockIndex(index)]; } + /** {@inheritDoc} */ @Override public T set(int index, T element) { if (index < 0 || size <= index) @@ -187,6 +193,7 @@ public class BlockList extends AbstractList { } } + /** {@inheritDoc} */ @Override public boolean add(T element) { int i = tailBlkIdx; @@ -217,6 +224,7 @@ public class BlockList extends AbstractList { return true; } + /** {@inheritDoc} */ @Override public void add(int index, T element) { if (index == size) { @@ -238,6 +246,7 @@ public class BlockList extends AbstractList { } } + /** {@inheritDoc} */ @Override public T remove(int index) { if (index == size - 1) { @@ -277,6 +286,7 @@ public class BlockList extends AbstractList { tailBlock = directory[tailDirIdx]; } + /** {@inheritDoc} */ @Override public Iterator iterator() { return new MyIterator(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/CachedAuthenticator.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/CachedAuthenticator.java index 8677c690fb..9915bdf49b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/CachedAuthenticator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/CachedAuthenticator.java @@ -49,7 +49,9 @@ import java.net.PasswordAuthentication; import java.util.Collection; import java.util.concurrent.CopyOnWriteArrayList; -/** Abstract authenticator which remembers prior authentications. */ +/** + * Abstract authenticator which remembers prior authentications. + */ public abstract class CachedAuthenticator extends Authenticator { private static final Collection cached = new CopyOnWriteArrayList<>(); @@ -63,6 +65,7 @@ public abstract class CachedAuthenticator extends Authenticator { cached.add(ca); } + /** {@inheritDoc} */ @Override protected final PasswordAuthentication getPasswordAuthentication() { final String host = getRequestingHost(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/ChangeIdUtil.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/ChangeIdUtil.java index f1f6053e3b..c8e6645f57 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/ChangeIdUtil.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/ChangeIdUtil.java @@ -82,9 +82,11 @@ public class ChangeIdUtil { * @param firstParentId * parent id of previous commit or null * @param author - * the {@link PersonIdent} for the presumed author and time + * the {@link org.eclipse.jgit.lib.PersonIdent} for the presumed + * author and time * @param committer - * the {@link PersonIdent} for the presumed committer and time + * the {@link org.eclipse.jgit.lib.PersonIdent} for the presumed + * committer and time * @param message * The commit message * @return the change id SHA1 string (without the 'I') or null if the @@ -138,7 +140,9 @@ public class ChangeIdUtil { * line. * * @param message + * a message. * @param changeId + * a Change-Id. * @return a commit message with an inserted Change-Id line */ public static String insertId(String message, ObjectId changeId) { @@ -148,18 +152,21 @@ public class ChangeIdUtil { /** * Find the right place to insert a Change-Id and return it. *

- * If no Change-Id is found the Change-Id is inserted before - * the first footer line but after a Bug line. + * If no Change-Id is found the Change-Id is inserted before the first + * footer line but after a Bug line. * - * If Change-Id is found and replaceExisting is set to false, - * the message is unchanged. + * If Change-Id is found and replaceExisting is set to false, the message is + * unchanged. * - * If Change-Id is found and replaceExisting is set to true, - * the Change-Id is replaced with {@code changeId}. + * If Change-Id is found and replaceExisting is set to true, the Change-Id + * is replaced with {@code changeId}. * * @param message + * a message. * @param changeId + * a Change-Id. * @param replaceExisting + * a boolean. * @return a commit message with an inserted Change-Id line */ public static String insertId(String message, ObjectId changeId, @@ -219,6 +226,7 @@ public class ChangeIdUtil { * only lines matching {@code footerPattern}. * * @param message + * a message. * @param delimiter * the line delimiter, like "\n" or "\r\n", needed to find the * footer diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS.java index 37e8347976..b43a7612de 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS.java @@ -75,7 +75,9 @@ import org.eclipse.jgit.util.ProcessResult.Status; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -/** Abstraction to support various file system operations not in Java. */ +/** + * Abstraction to support various file system operations not in Java. + */ public abstract class FS { private static final Logger LOG = LoggerFactory.getLogger(FS.class); @@ -192,7 +194,6 @@ public abstract class FS { * * * Note: this parameter is only relevant on Windows. - * * @return detected file system abstraction */ public static FS detect(Boolean cygwinUsed) { @@ -224,7 +225,11 @@ public abstract class FS { gitSystemConfig = src.gitSystemConfig; } - /** @return a new instance of the same type of FS. */ + /** + * Create a new instance of the same type of FS. + * + * @return a new instance of the same type of FS. + */ public abstract FS newInstance(); /** @@ -242,8 +247,8 @@ public abstract class FS { * parallel only one will succeed. In such cases both clients may think they * created a new file. * - * @return true if this implementation support atomic creation of new - * Files by {@link File#createNewFile()} + * @return true if this implementation support atomic creation of new Files + * by {@link java.io.File#createNewFile()} * @since 4.5 */ public boolean supportsAtomicCreateNewFile() { @@ -305,8 +310,9 @@ public abstract class FS { * than that of the link target. * * @param f + * a {@link java.io.File} object. * @return last modified time of f - * @throws IOException + * @throws java.io.IOException * @since 3.0 */ public long lastModified(File f) throws IOException { @@ -318,8 +324,10 @@ public abstract class FS { * symbolic links, the link is modified, not the target, * * @param f + * a {@link java.io.File} object. * @param time - * @throws IOException + * last modified time + * @throws java.io.IOException * @since 3.0 */ public void setLastModified(File f, long time) throws IOException { @@ -331,8 +339,9 @@ public abstract class FS { * it's the length of the link, else the length of the target. * * @param path + * a {@link java.io.File} object. * @return length of a file - * @throws IOException + * @throws java.io.IOException * @since 3.0 */ public long length(File path) throws IOException { @@ -343,7 +352,8 @@ public abstract class FS { * Delete a file. Throws an exception if delete fails. * * @param f - * @throws IOException + * a {@link java.io.File} object. + * @throws java.io.IOException * this may be a Java7 subclass with detailed information * @since 3.3 */ @@ -444,7 +454,7 @@ public abstract class FS { * Files to search for in the given path * @return the first match found, or null * @since 3.0 - **/ + */ protected static File searchPath(final String path, final String... lookFor) { if (path == null) return null; @@ -470,7 +480,7 @@ public abstract class FS { * to be used to parse the command's output * @return the one-line output of the command or {@code null} if there is * none - * @throws CommandFailedException + * @throws org.eclipse.jgit.errors.CommandFailedException * thrown when the command failed (return code was non-zero) */ @Nullable @@ -493,7 +503,7 @@ public abstract class FS { * current process * @return the one-line output of the command or {@code null} if there is * none - * @throws CommandFailedException + * @throws org.eclipse.jgit.errors.CommandFailedException * thrown when the command failed (return code was non-zero) * @since 4.0 */ @@ -632,6 +642,8 @@ public abstract class FS { } /** + * Discover the path to the Git executable. + * * @return the path to the Git executable or {@code null} if it cannot be * determined. * @since 4.0 @@ -639,6 +651,8 @@ public abstract class FS { protected abstract File discoverGitExe(); /** + * Discover the path to the system-wide Git configuration file + * * @return the path to the system-wide Git configuration file or * {@code null} if it cannot be determined. * @since 4.0 @@ -686,8 +700,10 @@ public abstract class FS { } /** - * @return the currently used path to the system-wide Git configuration - * file or {@code null} if none has been set. + * Get the currently used path to the system-wide Git configuration file. + * + * @return the currently used path to the system-wide Git configuration file + * or {@code null} if none has been set. * @since 4.0 */ public File getGitSystemConfig() { @@ -711,7 +727,10 @@ public abstract class FS { } /** + * Get the parent directory of this file's parent directory + * * @param grandchild + * a {@link java.io.File} object. * @return the parent directory of this file's parent directory or * {@code null} in case there's no grandparent directory * @since 4.0 @@ -729,8 +748,9 @@ public abstract class FS { * Check if a file is a symbolic link and read it * * @param path + * a {@link java.io.File} object. * @return target of link or null - * @throws IOException + * @throws java.io.IOException * @since 3.0 */ public String readSymLink(File path) throws IOException { @@ -738,9 +758,12 @@ public abstract class FS { } /** + * Whether the path is a symbolic link (and we support these). + * * @param path + * a {@link java.io.File} object. * @return true if the path is a symbolic link (and we support these) - * @throws IOException + * @throws java.io.IOException * @since 3.0 */ public boolean isSymLink(File path) throws IOException { @@ -752,6 +775,7 @@ public abstract class FS { * target does not exist * * @param path + * a {@link java.io.File} object. * @return true if path exists * @since 3.0 */ @@ -764,6 +788,7 @@ public abstract class FS { * path is a symbolic link to a directory, this method returns false. * * @param path + * a {@link java.io.File} object. * @return true if file is a directory, * @since 3.0 */ @@ -776,6 +801,7 @@ public abstract class FS { * symbolic links the test returns false if path represents a symbolic link. * * @param path + * a {@link java.io.File} object. * @return true if path represents a regular file * @since 3.0 */ @@ -784,10 +810,14 @@ public abstract class FS { } /** + * Whether path is hidden, either starts with . on unix or has the hidden + * attribute in windows + * * @param path + * a {@link java.io.File} object. * @return true if path is hidden, either starts with . on unix or has the * hidden attribute in windows - * @throws IOException + * @throws java.io.IOException * @since 3.0 */ public boolean isHidden(File path) throws IOException { @@ -798,8 +828,10 @@ public abstract class FS { * Set the hidden attribute for file whose name starts with a period. * * @param path + * a {@link java.io.File} object. * @param hidden - * @throws IOException + * whether to set the file hidden + * @throws java.io.IOException * @since 3.0 */ public void setHidden(File path, boolean hidden) throws IOException { @@ -810,8 +842,10 @@ public abstract class FS { * Create a symbolic link * * @param path + * a {@link java.io.File} object. * @param target - * @throws IOException + * target path of the symlink + * @throws java.io.IOException * @since 3.0 */ public void createSymLink(File path, String target) throws IOException { @@ -819,15 +853,15 @@ public abstract class FS { } /** - * Create a new file. See {@link File#createNewFile()}. Subclasses of this - * class may take care to provide a safe implementation for this even if - * {@link #supportsAtomicCreateNewFile()} is false + * Create a new file. See {@link java.io.File#createNewFile()}. Subclasses + * of this class may take care to provide a safe implementation for this + * even if {@link #supportsAtomicCreateNewFile()} is false * * @param path * the file to be created * @return true if the file was created, false if * the file already existed - * @throws IOException + * @throws java.io.IOException * @since 4.5 */ public boolean createNewFile(File path) throws IOException { @@ -835,7 +869,8 @@ public abstract class FS { } /** - * See {@link FileUtils#relativizePath(String, String, String, boolean)}. + * See + * {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}. * * @param base * The path against which other should be @@ -868,7 +903,7 @@ public abstract class FS { * Arguments to pass to this hook. Cannot be null, * but can be an empty array. * @return The ProcessResult describing this hook's execution. - * @throws JGitInternalException + * @throws org.eclipse.jgit.api.errors.JGitInternalException * if we fail to run the hook somehow. Causes may include an * interrupted process or I/O errors. * @since 4.0 @@ -903,7 +938,7 @@ public abstract class FS { * A string to pass on to the standard input of the hook. May be * null. * @return The ProcessResult describing this hook's execution. - * @throws JGitInternalException + * @throws org.eclipse.jgit.api.errors.JGitInternalException * if we fail to run the hook somehow. Causes may include an * interrupted process or I/O errors. * @since 4.0 @@ -939,7 +974,7 @@ public abstract class FS { * A string to pass on to the standard input of the hook. May be * null. * @return The ProcessResult describing this hook's execution. - * @throws JGitInternalException + * @throws org.eclipse.jgit.api.errors.JGitInternalException * if we fail to run the hook somehow. Causes may include an * interrupted process or I/O errors. * @since 4.0 @@ -984,8 +1019,8 @@ public abstract class FS { * The repository within which to find a hook. * @param hookName * The name of the hook we're trying to find. - * @return The {@link File} containing this particular hook if it exists in - * the given repository, null otherwise. + * @return The {@link java.io.File} containing this particular hook if it + * exists in the given repository, null otherwise. * @since 4.0 */ public File findHook(Repository repository, final String hookName) { @@ -1015,9 +1050,9 @@ public abstract class FS { * A string to pass on to the standard input of the hook. Can be * null. * @return the exit value of this process. - * @throws IOException + * @throws java.io.IOException * if an I/O error occurs while executing this process. - * @throws InterruptedException + * @throws java.lang.InterruptedException * if the current thread is interrupted while waiting for the * process to end. * @since 4.2 @@ -1051,9 +1086,9 @@ public abstract class FS { * will be consumed by the process. The method will close the * inputstream after all bytes are read. * @return the return code of this process. - * @throws IOException + * @throws java.io.IOException * if an I/O error occurs while executing this process. - * @throws InterruptedException + * @throws java.lang.InterruptedException * if the current thread is interrupted while waiting for the * process to end. * @since 4.2 @@ -1179,15 +1214,15 @@ public abstract class FS { public abstract ProcessBuilder runInShell(String cmd, String[] args); /** - * Execute a command defined by a {@link ProcessBuilder}. + * Execute a command defined by a {@link java.lang.ProcessBuilder}. * * @param pb * The command to be executed * @param in * The standard input stream passed to the process * @return The result of the executed command - * @throws InterruptedException - * @throws IOException + * @throws java.lang.InterruptedException + * @throws java.io.IOException * @since 4.2 */ public ExecutionResult execute(ProcessBuilder pb, InputStream in) @@ -1340,8 +1375,11 @@ public abstract class FS { } /** + * Get the file attributes we care for. + * * @param path - * @return the file attributes we care for + * a {@link java.io.File} object. + * @return the file attributes we care for. * @since 3.3 */ public Attributes getAttributes(File path) { @@ -1361,6 +1399,7 @@ public abstract class FS { * Normalize the unicode path to composed form. * * @param file + * a {@link java.io.File} object. * @return NFC-format File * @since 3.3 */ @@ -1372,6 +1411,7 @@ public abstract class FS { * Normalize the unicode path to composed form. * * @param name + * path name * @return NFC-format string * @since 3.3 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_POSIX.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_POSIX.java index 969afd2a97..a2923db9dd 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_POSIX.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_POSIX.java @@ -86,7 +86,9 @@ public class FS_POSIX extends FS { SUPPORTED, NOT_SUPPORTED, UNDEFINED } - /** Default constructor. */ + /** + * Default constructor. + */ protected FS_POSIX() { } @@ -134,6 +136,7 @@ public class FS_POSIX extends FS { } } + /** {@inheritDoc} */ @Override public FS newInstance() { return new FS_POSIX(this); @@ -181,6 +184,7 @@ public class FS_POSIX extends FS { } } + /** {@inheritDoc} */ @Override protected File discoverGitExe() { String path = SystemReader.getInstance().getenv("PATH"); //$NON-NLS-1$ @@ -211,21 +215,25 @@ public class FS_POSIX extends FS { return gitExe; } + /** {@inheritDoc} */ @Override public boolean isCaseSensitive() { return !SystemReader.getInstance().isMacOS(); } + /** {@inheritDoc} */ @Override public boolean supportsExecute() { return true; } + /** {@inheritDoc} */ @Override public boolean canExecute(File f) { return FileUtils.canExecute(f); } + /** {@inheritDoc} */ @Override public boolean setExecute(File f, boolean canExecute) { if (!isFile(f)) @@ -266,6 +274,7 @@ public class FS_POSIX extends FS { } } + /** {@inheritDoc} */ @Override public ProcessBuilder runInShell(String cmd, String[] args) { List argv = new ArrayList<>(4 + args.length); @@ -279,9 +288,7 @@ public class FS_POSIX extends FS { return proc; } - /** - * @since 4.0 - */ + /** {@inheritDoc} */ @Override public ProcessResult runHookIfPresent(Repository repository, String hookName, String[] args, PrintStream outRedirect, PrintStream errRedirect, @@ -290,48 +297,43 @@ public class FS_POSIX extends FS { errRedirect, stdinArgs); } + /** {@inheritDoc} */ @Override public boolean retryFailedLockFileCommit() { return false; } + /** {@inheritDoc} */ @Override public boolean supportsSymlinks() { return true; } + /** {@inheritDoc} */ @Override public void setHidden(File path, boolean hidden) throws IOException { // no action on POSIX } - /** - * @since 3.3 - */ + /** {@inheritDoc} */ @Override public Attributes getAttributes(File path) { return FileUtils.getFileAttributesPosix(this, path); } - /** - * @since 3.3 - */ + /** {@inheritDoc} */ @Override public File normalize(File file) { return FileUtils.normalize(file); } - /** - * @since 3.3 - */ + /** {@inheritDoc} */ @Override public String normalize(String name) { return FileUtils.normalize(name); } - /** - * @since 3.7 - */ + /** {@inheritDoc} */ @Override public File findHook(Repository repository, String hookName) { final File gitdir = repository.getDirectory(); @@ -345,6 +347,7 @@ public class FS_POSIX extends FS { return null; } + /** {@inheritDoc} */ @Override public boolean supportsAtomicCreateNewFile() { if (supportsAtomicCreateNewFile == AtomicFileCreation.UNDEFINED) { @@ -356,13 +359,15 @@ public class FS_POSIX extends FS { @Override @SuppressWarnings("boxing") /** + * {@inheritDoc} + *

* An implementation of the File#createNewFile() semantics which works also * on NFS. If the config option * {@code core.supportsAtomicCreateNewFile = true} (which is the default) * then simply File#createNewFile() is called. * * But if {@code core.supportsAtomicCreateNewFile = false} then after - * successful creation of the lock file a hardlink to that lock file is + * successful creation of the lock file a hard link to that lock file is * created and the attribute nlink of the lock file is checked to be 2. If * multiple clients manage to create the same lock file nlink would be * greater than 2 showing the error. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32.java index 060292160e..29fe5dc829 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32.java @@ -83,36 +83,43 @@ public class FS_Win32 extends FS { super(src); } + /** {@inheritDoc} */ @Override public FS newInstance() { return new FS_Win32(this); } + /** {@inheritDoc} */ @Override public boolean supportsExecute() { return false; } + /** {@inheritDoc} */ @Override public boolean canExecute(final File f) { return false; } + /** {@inheritDoc} */ @Override public boolean setExecute(final File f, final boolean canExec) { return false; } + /** {@inheritDoc} */ @Override public boolean isCaseSensitive() { return false; } + /** {@inheritDoc} */ @Override public boolean retryFailedLockFileCommit() { return true; } + /** {@inheritDoc} */ @Override protected File discoverGitExe() { String path = SystemReader.getInstance().getenv("PATH"); //$NON-NLS-1$ @@ -141,6 +148,7 @@ public class FS_Win32 extends FS { return gitExe; } + /** {@inheritDoc} */ @Override protected File userHomeImpl() { String home = SystemReader.getInstance().getenv("HOME"); //$NON-NLS-1$ @@ -160,6 +168,7 @@ public class FS_Win32 extends FS { return super.userHomeImpl(); } + /** {@inheritDoc} */ @Override public ProcessBuilder runInShell(String cmd, String[] args) { List argv = new ArrayList<>(3 + args.length); @@ -172,6 +181,7 @@ public class FS_Win32 extends FS { return proc; } + /** {@inheritDoc} */ @Override public boolean supportsSymlinks() { if (supportSymlinks == null) @@ -200,9 +210,7 @@ public class FS_Win32 extends FS { } } - /** - * @since 3.3 - */ + /** {@inheritDoc} */ @Override public Attributes getAttributes(File path) { return FileUtils.getFileAttributesBasic(this, path); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32_Cygwin.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32_Cygwin.java index 545cc0119e..64cdcc300d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32_Cygwin.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32_Cygwin.java @@ -72,6 +72,8 @@ public class FS_Win32_Cygwin extends FS_Win32 { private static String cygpath; /** + * Whether cygwin is found + * * @return true if cygwin is found */ public static boolean isCygwin() { @@ -107,11 +109,13 @@ public class FS_Win32_Cygwin extends FS_Win32 { super(src); } + /** {@inheritDoc} */ @Override public FS newInstance() { return new FS_Win32_Cygwin(this); } + /** {@inheritDoc} */ @Override public File resolve(final File dir, final String pn) { String useCygPath = System.getProperty("jgit.usecygpath"); //$NON-NLS-1$ @@ -132,6 +136,7 @@ public class FS_Win32_Cygwin extends FS_Win32 { return super.resolve(dir, pn); } + /** {@inheritDoc} */ @Override protected File userHomeImpl() { final String home = AccessController @@ -146,6 +151,7 @@ public class FS_Win32_Cygwin extends FS_Win32 { return resolve(new File("."), home); //$NON-NLS-1$ } + /** {@inheritDoc} */ @Override public ProcessBuilder runInShell(String cmd, String[] args) { List argv = new ArrayList<>(4 + args.length); @@ -159,18 +165,14 @@ public class FS_Win32_Cygwin extends FS_Win32 { return proc; } - /** - * @since 3.7 - */ + /** {@inheritDoc} */ @Override public String relativize(String base, String other) { final String relativized = super.relativize(base, other); return relativized.replace(File.separatorChar, '/'); } - /** - * @since 4.0 - */ + /** {@inheritDoc} */ @Override public ProcessResult runHookIfPresent(Repository repository, String hookName, String[] args, PrintStream outRedirect, PrintStream errRedirect, @@ -179,9 +181,7 @@ public class FS_Win32_Cygwin extends FS_Win32 { errRedirect, stdinArgs); } - /** - * @since 3.7 - */ + /** {@inheritDoc} */ @Override public File findHook(Repository repository, String hookName) { final File gitdir = repository.getDirectory(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtil.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtil.java index b87b9a41d3..96f21756d5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtil.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtil.java @@ -45,7 +45,6 @@ package org.eclipse.jgit.util; import java.io.File; import java.io.IOException; -import java.nio.file.Files; import org.eclipse.jgit.util.FS.Attributes; @@ -56,10 +55,14 @@ import org.eclipse.jgit.util.FS.Attributes; public class FileUtil { /** + * Read target path of a symlink. + * * @param path - * @return target path of the symlink - * @throws IOException - * @deprecated use {@link FileUtils#readSymLink(File)} instead + * a {@link java.io.File}. + * @return target path of the symlink. + * @throws java.io.IOException + * @deprecated use {@link org.eclipse.jgit.util.FileUtils#readSymLink(File)} + * instead */ @Deprecated public static String readSymlink(File path) throws IOException { @@ -67,12 +70,16 @@ public class FileUtil { } /** + * Create a symlink + * * @param path * path of the symlink to be created * @param target * target of the symlink to be created - * @throws IOException - * @deprecated use {@link FileUtils#createSymLink(File, String)} instead + * @throws java.io.IOException + * @deprecated use + * {@link org.eclipse.jgit.util.FileUtils#createSymLink(File, String)} + * instead */ @Deprecated public static void createSymLink(File path, String target) @@ -81,9 +88,14 @@ public class FileUtil { } /** + * Whether the passed file is a symlink + * * @param path + * a {@link java.io.File} object. * @return {@code true} if the passed path is a symlink - * @deprecated Use {@link Files#isSymbolicLink(java.nio.file.Path)} instead + * @deprecated Use + * {@link java.nio.file.Files#isSymbolicLink(java.nio.file.Path)} + * instead */ @Deprecated public static boolean isSymlink(File path) { @@ -91,11 +103,14 @@ public class FileUtil { } /** + * Get lastModified attribute for given path + * * @param path + * a {@link java.io.File}. * @return lastModified attribute for given path - * @throws IOException + * @throws java.io.IOException * @deprecated Use - * {@link Files#getLastModifiedTime(java.nio.file.Path, java.nio.file.LinkOption...)} + * {@link java.nio.file.Files#getLastModifiedTime(java.nio.file.Path, java.nio.file.LinkOption...)} * instead */ @Deprecated @@ -104,11 +119,15 @@ public class FileUtil { } /** + * Set lastModified attribute for given path + * * @param path + * a {@link java.io.File}. * @param time - * @throws IOException + * a long. + * @throws java.io.IOException * @deprecated Use - * {@link Files#setLastModifiedTime(java.nio.file.Path, java.nio.file.attribute.FileTime)} + * {@link java.nio.file.Files#setLastModifiedTime(java.nio.file.Path, java.nio.file.attribute.FileTime)} * instead */ @Deprecated @@ -117,10 +136,13 @@ public class FileUtil { } /** + * Whether this file exists + * * @param path + * a {@link java.io.File}. * @return {@code true} if the given path exists * @deprecated Use - * {@link Files#exists(java.nio.file.Path, java.nio.file.LinkOption...)} + * {@link java.nio.file.Files#exists(java.nio.file.Path, java.nio.file.LinkOption...)} * instead */ @Deprecated @@ -129,10 +151,14 @@ public class FileUtil { } /** + * Whether this file is hidden + * * @param path + * a {@link java.io.File}. * @return {@code true} if the given path is hidden - * @throws IOException - * @deprecated Use {@link Files#isHidden(java.nio.file.Path)} instead + * @throws java.io.IOException + * @deprecated Use {@link java.nio.file.Files#isHidden(java.nio.file.Path)} + * instead */ @Deprecated public static boolean isHidden(File path) throws IOException { @@ -140,10 +166,16 @@ public class FileUtil { } /** + * Set this file hidden + * * @param path + * a {@link java.io.File}. * @param hidden - * @throws IOException - * @deprecated Use {@link FileUtils#setHidden(File,boolean)} instead + * a boolean. + * @throws java.io.IOException + * @deprecated Use + * {@link org.eclipse.jgit.util.FileUtils#setHidden(File,boolean)} + * instead */ @Deprecated public static void setHidden(File path, boolean hidden) throws IOException { @@ -151,10 +183,14 @@ public class FileUtil { } /** + * Get file length + * * @param path + * a {@link java.io.File}. * @return length of the given file - * @throws IOException - * @deprecated Use {@link FileUtils#getLength(File)} instead + * @throws java.io.IOException + * @deprecated Use {@link org.eclipse.jgit.util.FileUtils#getLength(File)} + * instead */ @Deprecated public static long getLength(File path) throws IOException { @@ -162,10 +198,13 @@ public class FileUtil { } /** + * Whether the given File is a directory + * * @param path - * @return {@code true} if the given file a directory + * a {@link java.io.File} object. + * @return {@code true} if the given file is a directory * @deprecated Use - * {@link Files#isDirectory(java.nio.file.Path, java.nio.file.LinkOption...)} + * {@link java.nio.file.Files#isDirectory(java.nio.file.Path, java.nio.file.LinkOption...)} * instead */ @Deprecated @@ -174,10 +213,13 @@ public class FileUtil { } /** + * Whether the given File is a file + * * @param path + * a {@link java.io.File} object. * @return {@code true} if the given file is a file * @deprecated Use - * {@link Files#isRegularFile(java.nio.file.Path, java.nio.file.LinkOption...)} + * {@link java.nio.file.Files#isRegularFile(java.nio.file.Path, java.nio.file.LinkOption...)} * instead */ @Deprecated @@ -186,9 +228,13 @@ public class FileUtil { } /** + * Whether the given file can be executed + * * @param path + * a {@link java.io.File} object. * @return {@code true} if the given file can be executed - * @deprecated Use {@link FileUtils#canExecute(File)} instead + * @deprecated Use {@link org.eclipse.jgit.util.FileUtils#canExecute(File)} + * instead */ @Deprecated public static boolean canExecute(File path) { @@ -196,9 +242,12 @@ public class FileUtil { } /** + * Delete the given file + * * @param path - * @throws IOException - * @deprecated use {@link FileUtils#delete(File)} + * a {@link java.io.File} object. + * @throws java.io.IOException + * @deprecated use {@link org.eclipse.jgit.util.FileUtils#delete(File)} */ @Deprecated public static void delete(File path) throws IOException { @@ -206,10 +255,16 @@ public class FileUtil { } /** + * Get file system attributes for the given file + * * @param fs + * a {@link org.eclipse.jgit.util.FS} object. * @param path + * a {@link java.io.File} object. * @return file system attributes for the given file - * @deprecated Use {@link FileUtils#getFileAttributesPosix(FS,File)} instead + * @deprecated Use + * {@link org.eclipse.jgit.util.FileUtils#getFileAttributesPosix(FS,File)} + * instead */ @Deprecated public static Attributes getFileAttributesPosix(FS fs, File path) { @@ -217,9 +272,14 @@ public class FileUtil { } /** + * NFC normalize File (on Mac), otherwise do nothing + * * @param file - * @return on Mac: NFC normalized {@link File}, otherwise the passed file - * @deprecated Use {@link FileUtils#normalize(File)} instead + * a {@link java.io.File}. + * @return on Mac: NFC normalized {@link java.io.File}, otherwise the passed + * file + * @deprecated Use {@link org.eclipse.jgit.util.FileUtils#normalize(File)} + * instead */ @Deprecated public static File normalize(File file) { @@ -227,9 +287,13 @@ public class FileUtil { } /** + * NFC normalize file name (on Mac), otherwise do nothing + * * @param name + * a {@link java.lang.String} object. * @return on Mac: NFC normalized form of given name - * @deprecated Use {@link FileUtils#normalize(String)} instead + * @deprecated Use {@link org.eclipse.jgit.util.FileUtils#normalize(String)} + * instead */ @Deprecated public static String normalize(String name) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtils.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtils.java index 2b6c8c94df..a1c479553e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtils.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtils.java @@ -47,7 +47,6 @@ package org.eclipse.jgit.util; import java.io.File; import java.io.IOException; -import java.nio.channels.FileLock; import java.nio.file.AtomicMoveNotSupportedException; import java.nio.file.CopyOption; import java.nio.file.Files; @@ -118,10 +117,9 @@ public class FileUtils { * @param f * {@code File} to be converted to {@code Path} * @return the path represented by the file - * @throws IOException + * @throws java.io.IOException * in case the path represented by the file is not valid ( * {@link java.nio.file.InvalidPathException}) - * * @since 4.10 */ public static Path toPath(final File f) throws IOException { @@ -137,11 +135,11 @@ public class FileUtils { * * @param f * {@code File} to be deleted - * @throws IOException + * @throws java.io.IOException * if deletion of {@code f} fails. This may occur if {@code f} * didn't exist when the method was called. This can therefore - * cause IOExceptions during race conditions when multiple - * concurrent threads all try to delete the same file. + * cause java.io.IOExceptions during race conditions when + * multiple concurrent threads all try to delete the same file. */ public static void delete(final File f) throws IOException { delete(f, NONE); @@ -157,12 +155,12 @@ public class FileUtils { * a subtree, {@code RETRY} to retry when deletion failed. * Retrying may help if the underlying file system doesn't allow * deletion of files being read by another thread. - * @throws IOException + * @throws java.io.IOException * if deletion of {@code f} fails. This may occur if {@code f} * didn't exist when the method was called. This can therefore - * cause IOExceptions during race conditions when multiple - * concurrent threads all try to delete the same file. This - * exception is not thrown when IGNORE_ERRORS is set. + * cause java.io.IOExceptions during race conditions when + * multiple concurrent threads all try to delete the same file. + * This exception is not thrown when IGNORE_ERRORS is set. */ public static void delete(final File f, int options) throws IOException { FS fs = FS.DETECTED; @@ -239,7 +237,7 @@ public class FileUtils { * the old {@code File} * @param dst * the new {@code File} - * @throws IOException + * @throws java.io.IOException * if the rename has failed * @since 3.0 */ @@ -249,18 +247,20 @@ public class FileUtils { } /** - * Rename a file or folder using the passed {@link CopyOption}s. If the - * rename fails and if we are running on a filesystem where it makes sense - * to repeat a failing rename then repeat the rename operation up to 9 times - * with 100ms sleep time between two calls. Furthermore if the destination - * exists and is a directory hierarchy with only directories in it, the - * whole directory hierarchy will be deleted. If the target represents a - * non-empty directory structure, empty subdirectories within that structure - * may or may not be deleted even if the method fails. Furthermore if the - * destination exists and is a file then the file will be replaced if - * {@link StandardCopyOption#REPLACE_EXISTING} has been set. If - * {@link StandardCopyOption#ATOMIC_MOVE} has been set the rename will be - * done atomically or fail with an {@link AtomicMoveNotSupportedException} + * Rename a file or folder using the passed + * {@link java.nio.file.CopyOption}s. If the rename fails and if we are + * running on a filesystem where it makes sense to repeat a failing rename + * then repeat the rename operation up to 9 times with 100ms sleep time + * between two calls. Furthermore if the destination exists and is a + * directory hierarchy with only directories in it, the whole directory + * hierarchy will be deleted. If the target represents a non-empty directory + * structure, empty subdirectories within that structure may or may not be + * deleted even if the method fails. Furthermore if the destination exists + * and is a file then the file will be replaced if + * {@link java.nio.file.StandardCopyOption#REPLACE_EXISTING} has been set. + * If {@link java.nio.file.StandardCopyOption#ATOMIC_MOVE} has been set the + * rename will be done atomically or fail with an + * {@link java.nio.file.AtomicMoveNotSupportedException} * * @param src * the old file @@ -268,10 +268,10 @@ public class FileUtils { * the new file * @param options * options to pass to - * {@link Files#move(java.nio.file.Path, java.nio.file.Path, CopyOption...)} - * @throws AtomicMoveNotSupportedException + * {@link java.nio.file.Files#move(java.nio.file.Path, java.nio.file.Path, CopyOption...)} + * @throws java.nio.file.AtomicMoveNotSupportedException * if file cannot be moved as an atomic file system operation - * @throws IOException + * @throws java.io.IOException * @since 4.1 */ public static void rename(final File src, final File dst, @@ -314,11 +314,12 @@ public class FileUtils { * * @param d * directory to be created - * @throws IOException + * @throws java.io.IOException * if creation of {@code d} fails. This may occur if {@code d} * did exist when the method was called. This can therefore - * cause IOExceptions during race conditions when multiple - * concurrent threads all try to create the same directory. + * cause java.io.IOExceptions during race conditions when + * multiple concurrent threads all try to create the same + * directory. */ public static void mkdir(final File d) throws IOException { @@ -333,11 +334,12 @@ public class FileUtils { * @param skipExisting * if {@code true} skip creation of the given directory if it * already exists in the file system - * @throws IOException + * @throws java.io.IOException * if creation of {@code d} fails. This may occur if {@code d} * did exist when the method was called. This can therefore - * cause IOExceptions during race conditions when multiple - * concurrent threads all try to create the same directory. + * cause java.io.IOExceptions during race conditions when + * multiple concurrent threads all try to create the same + * directory. */ public static void mkdir(final File d, boolean skipExisting) throws IOException { @@ -357,11 +359,12 @@ public class FileUtils { * * @param d * directory to be created - * @throws IOException + * @throws java.io.IOException * if creation of {@code d} fails. This may occur if {@code d} * did exist when the method was called. This can therefore - * cause IOExceptions during race conditions when multiple - * concurrent threads all try to create the same directory. + * cause java.io.IOExceptions during race conditions when + * multiple concurrent threads all try to create the same + * directory. */ public static void mkdirs(final File d) throws IOException { mkdirs(d, false); @@ -378,11 +381,12 @@ public class FileUtils { * @param skipExisting * if {@code true} skip creation of the given directory if it * already exists in the file system - * @throws IOException + * @throws java.io.IOException * if creation of {@code d} fails. This may occur if {@code d} * did exist when the method was called. This can therefore - * cause IOExceptions during race conditions when multiple - * concurrent threads all try to create the same directory. + * cause java.io.IOExceptions during race conditions when + * multiple concurrent threads all try to create the same + * directory. */ public static void mkdirs(final File d, boolean skipExisting) throws IOException { @@ -402,12 +406,12 @@ public class FileUtils { * filesystem activities that might affect the file. *

* Note: this method should not be used for file-locking, as the resulting - * protocol cannot be made to work reliably. The {@link FileLock} facility - * should be used instead. + * protocol cannot be made to work reliably. The + * {@link java.nio.channels.FileLock} facility should be used instead. * * @param f * the file to be created - * @throws IOException + * @throws java.io.IOException * if the named file already exists or if an I/O error occurred */ public static void createNewFile(File f) throws IOException { @@ -424,7 +428,7 @@ public class FileUtils { * @param target * the target of the symbolic link * @return the path to the symbolic link - * @throws IOException + * @throws java.io.IOException * @since 4.2 */ public static Path createSymLink(File path, String target) @@ -447,9 +451,12 @@ public class FileUtils { } /** + * Read target path of the symlink. + * * @param path + * a {@link java.io.File} object. * @return target path of the symlink, or null if it is not a symbolic link - * @throws IOException + * @throws java.io.IOException * @since 3.0 */ public static String readSymLink(File path) throws IOException { @@ -468,11 +475,13 @@ public class FileUtils { * Create a temporary directory. * * @param prefix + * prefix string * @param suffix + * suffix string * @param dir * The parent dir, can be null to use system default temp dir. * @return the temp dir created. - * @throws IOException + * @throws java.io.IOException * @since 3.4 */ public static File createTempDir(String prefix, String suffix, File dir) @@ -491,18 +500,19 @@ public class FileUtils { /** + * Relativize a path + * * @deprecated Use the more-clearly-named - * {@link FileUtils#relativizeNativePath(String, String)} + * {@link org.eclipse.jgit.util.FileUtils#relativizeNativePath(String, String)} * instead, or directly call - * {@link FileUtils#relativizePath(String, String, String, boolean)} + * {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)} * * Expresses other as a relative file path from * base. File-separator and case sensitivity are * based on the current file system. * * See also - * {@link FileUtils#relativizePath(String, String, String, boolean)}. - * + * {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}. * @param base * Base path * @param other @@ -516,15 +526,17 @@ public class FileUtils { } /** - * Expresses other as a relative file path from base. - * File-separator and case sensitivity are based on the current file system. + * Expresses other as a relative file path from + * base. File-separator and case sensitivity are based on the + * current file system. * - * See also {@link FileUtils#relativizePath(String, String, String, boolean)}. + * See also + * {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}. * * @param base * Base path * @param other - * Destination path + * Destination path * @return Relative path from base to other * @since 4.8 */ @@ -533,15 +545,17 @@ public class FileUtils { } /** - * Expresses other as a relative file path from base. - * File-separator and case sensitivity are based on Git's internal representation of files (which matches Unix). + * Expresses other as a relative file path from + * base. File-separator and case sensitivity are based on Git's + * internal representation of files (which matches Unix). * - * See also {@link FileUtils#relativizePath(String, String, String, boolean)}. + * See also + * {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}. * * @param base * Base path * @param other - * Destination path + * Destination path * @return Relative path from base to other * @since 4.8 */ @@ -620,6 +634,7 @@ public class FileUtils { * Determine if an IOException is a Stale NFS File Handle * * @param ioe + * an {@link java.io.IOException} object. * @return a boolean true if the IOException is a Stale NFS FIle Handle * @since 4.1 */ @@ -635,6 +650,7 @@ public class FileUtils { * File Handle * * @param throwable + * a {@link java.lang.Throwable} object. * @return a boolean true if the throwable or a cause in its causal chain is * a Stale NFS File Handle * @since 4.7 @@ -697,9 +713,13 @@ public class FileUtils { } /** + * Set a file hidden (on Windows) + * * @param file + * a {@link java.io.File} object. * @param hidden - * @throws IOException + * a boolean. + * @throws java.io.IOException * @since 4.1 */ public static void setHidden(File file, boolean hidden) throws IOException { @@ -708,9 +728,12 @@ public class FileUtils { } /** + * Get file length + * * @param file + * a {@link java.io.File}. * @return length of the given file - * @throws IOException + * @throws java.io.IOException * @since 4.1 */ public static long getLength(File file) throws IOException { @@ -740,8 +763,11 @@ public class FileUtils { } /** + * Whether the given file can be executed. + * * @param file - * @return {@code true} if the given file can be executed + * a {@link java.io.File} object. + * @return {@code true} if the given file can be executed. * @since 4.1 */ public static boolean canExecute(File file) { @@ -783,9 +809,13 @@ public class FileUtils { } /** + * Get file system attributes for the given file. + * * @param fs + * a {@link org.eclipse.jgit.util.FS} object. * @param file - * @return file system attributes for the given file + * a {@link java.io.File}. + * @return file system attributes for the given file. * @since 4.1 */ public static Attributes getFileAttributesPosix(FS fs, File file) { @@ -816,8 +846,12 @@ public class FileUtils { } /** + * NFC normalize a file (on Mac), otherwise do nothing + * * @param file - * @return on Mac: NFC normalized {@link File}, otherwise the passed file + * a {@link java.io.File}. + * @return on Mac: NFC normalized {@link java.io.File}, otherwise the passed + * file * @since 4.1 */ public static File normalize(File file) { @@ -832,7 +866,10 @@ public class FileUtils { } /** + * On Mac: get NFC normalized form of given name, otherwise the given name. + * * @param name + * a {@link java.lang.String} object. * @return on Mac: NFC normalized form of given name * @since 4.1 */ @@ -846,16 +883,16 @@ public class FileUtils { } /** - * Best-effort variation of {@link File#getCanonicalFile()} returning the - * input file if the file cannot be canonicalized instead of throwing - * {@link IOException}. + * Best-effort variation of {@link java.io.File#getCanonicalFile()} + * returning the input file if the file cannot be canonicalized instead of + * throwing {@link java.io.IOException}. * * @param file * to be canonicalized; may be {@code null} * @return canonicalized file, or the unchanged input file if * canonicalization failed or if {@code file == null} - * @throws SecurityException - * if {@link File#getCanonicalFile()} throws one + * @throws java.lang.SecurityException + * if {@link java.io.File#getCanonicalFile()} throws one * @since 4.2 */ public static File canonicalize(File file) { @@ -873,6 +910,7 @@ public class FileUtils { * Convert a path to String, replacing separators as necessary. * * @param file + * a {@link java.io.File}. * @return file's path as a String * @since 4.10 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateFormatter.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateFormatter.java index d7ab5f882b..e461902a31 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateFormatter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateFormatter.java @@ -54,7 +54,8 @@ import org.eclipse.jgit.lib.PersonIdent; * A utility for formatting dates according to the Git log.date formats plus * extensions. *

- * The enum {@link Format} defines the available types. + * The enum {@link org.eclipse.jgit.util.GitDateFormatter.Format} defines the + * available types. */ public class GitDateFormatter { @@ -119,6 +120,8 @@ public class GitDateFormatter { * Create a new Git oriented date formatter * * @param format + * a {@link org.eclipse.jgit.util.GitDateFormatter.Format} + * object. */ public GitDateFormatter(Format format) { this.format = format; @@ -159,6 +162,7 @@ public class GitDateFormatter { * specification. * * @param ident + * a {@link org.eclipse.jgit.lib.PersonIdent} object. * @return formatted version of date, time and time zone */ @SuppressWarnings("boxing") diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateParser.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateParser.java index da78008a0b..a339b9aba0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateParser.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateParser.java @@ -55,7 +55,7 @@ import java.util.Map; import org.eclipse.jgit.internal.JGitText; /** - * Parses strings with time and date specifications into {@link Date}. + * Parses strings with time and date specifications into {@link java.util.Date}. * * When git needs to parse strings specified by the user this parser can be * used. One example is the parsing of the config parameter gc.pruneexpire. The @@ -134,16 +134,17 @@ public class GitDateParser { } /** - * Parses a string into a {@link Date} using the default locale. Since this - * parser also supports relative formats (e.g. "yesterday") the caller can - * specify the reference date. These types of strings can be parsed: + * Parses a string into a {@link java.util.Date} using the default locale. + * Since this parser also supports relative formats (e.g. "yesterday") the + * caller can specify the reference date. These types of strings can be + * parsed: *

    *
  • "never"
    • *
  • "now"
    • *
  • "yesterday"
    • *
  • "(x) years|months|weeks|days|hours|minutes|seconds ago"
    - * Multiple specs can be combined like in "2 weeks 3 days ago". Instead of - * ' ' one can use '.' to seperate the words
    • + * Multiple specs can be combined like in "2 weeks 3 days ago". Instead of ' + * ' one can use '.' to seperate the words *
  • "yyyy-MM-dd HH:mm:ss Z" (ISO)
    • *
  • "EEE, dd MMM yyyy HH:mm:ss Z" (RFC)
    • *
  • "yyyy-MM-dd"
    • @@ -161,11 +162,12 @@ public class GitDateParser { * formats. E.g. if baseDate is "25.8.2012" then parsing of the * string "1 week ago" would result in a date corresponding to * "18.8.2012". This is used when a JGit command calls this - * parser often but wants a consistent starting point for calls.
    + * parser often but wants a consistent starting point for + * calls.
    * If set to null then the current time will be used * instead. - * @return the parsed {@link Date} - * @throws ParseException + * @return the parsed {@link java.util.Date} + * @throws java.text.ParseException * if the given dateStr was not recognized */ public static Date parse(String dateStr, Calendar now) @@ -174,16 +176,17 @@ public class GitDateParser { } /** - * Parses a string into a {@link Date} using the given locale. Since this - * parser also supports relative formats (e.g. "yesterday") the caller can - * specify the reference date. These types of strings can be parsed: + * Parses a string into a {@link java.util.Date} using the given locale. + * Since this parser also supports relative formats (e.g. "yesterday") the + * caller can specify the reference date. These types of strings can be + * parsed: *
      *
    • "never"
      • *
    • "now"
      • *
    • "yesterday"
      • *
    • "(x) years|months|weeks|days|hours|minutes|seconds ago"
      - * Multiple specs can be combined like in "2 weeks 3 days ago". Instead of - * ' ' one can use '.' to seperate the words
      • + * Multiple specs can be combined like in "2 weeks 3 days ago". Instead of ' + * ' one can use '.' to seperate the words *
    • "yyyy-MM-dd HH:mm:ss Z" (ISO)
      • *
    • "EEE, dd MMM yyyy HH:mm:ss Z" (RFC)
      • *
    • "yyyy-MM-dd"
      • @@ -201,13 +204,14 @@ public class GitDateParser { * formats. E.g. if baseDate is "25.8.2012" then parsing of the * string "1 week ago" would result in a date corresponding to * "18.8.2012". This is used when a JGit command calls this - * parser often but wants a consistent starting point for calls.
      + * parser often but wants a consistent starting point for + * calls.
      * If set to null then the current time will be used * instead. * @param locale * locale to be used to parse the date string - * @return the parsed {@link Date} - * @throws ParseException + * @return the parsed {@link java.util.Date} + * @throws java.text.ParseException * if the given dateStr was not recognized * @since 3.2 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/Holder.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/Holder.java index 3563e1bf1d..b4cc6ca33f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/Holder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/Holder.java @@ -45,14 +45,15 @@ package org.eclipse.jgit.util; * Holder of an object. * * @param - * the type of value held by this {@link Holder} - * + * the type of value held by this {@link org.eclipse.jgit.util.Holder} * @since 4.3 */ public class Holder { private T value; /** + *

      Constructor for Holder.

      + * * @param value * is the initial value that is {@link #set(Object)} */ @@ -61,15 +62,20 @@ public class Holder { } /** - * @return the value held by this {@link Holder} + * Get the value held by this {@link org.eclipse.jgit.util.Holder} + * + * @return the value held by this {@link org.eclipse.jgit.util.Holder} */ public T get() { return value; } /** + * Set a new value held by this {@link org.eclipse.jgit.util.Holder} + * * @param value - * to be set as new value held by this {@link Holder} + * to be set as new value held by this + * {@link org.eclipse.jgit.util.Holder} */ public void set(T value) { this.value = value; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/HttpSupport.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/HttpSupport.java index 13e61a7972..a5a858f85e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/HttpSupport.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/HttpSupport.java @@ -65,7 +65,9 @@ import javax.net.ssl.X509TrustManager; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.transport.http.HttpConnection; -/** Extra utilities to support usage of HTTP. */ +/** + * Extra utilities to support usage of HTTP. + */ public class HttpSupport { /** The {@code GET} HTTP method. */ public static final String METHOD_GET = "GET"; //$NON-NLS-1$ @@ -192,8 +194,9 @@ public class HttpSupport { * @param c * connection the code should be obtained from. * @return r HTTP status code, usually 200 to indicate success. See - * {@link HttpConnection} for other defined constants. - * @throws IOException + * {@link org.eclipse.jgit.transport.http.HttpConnection} for other + * defined constants. + * @throws java.io.IOException * communications error prevented obtaining the response code. * @since 3.3 */ @@ -220,8 +223,9 @@ public class HttpSupport { * @param c * connection the code should be obtained from. * @return r HTTP status code, usually 200 to indicate success. See - * {@link HttpConnection} for other defined constants. - * @throws IOException + * {@link org.eclipse.jgit.transport.http.HttpConnection} for other + * defined constants. + * @throws java.io.IOException * communications error prevented obtaining the response code. */ public static int response(final java.net.HttpURLConnection c) @@ -248,7 +252,7 @@ public class HttpSupport { * @param headerName * the header name * @return the header value - * @throws IOException + * @throws java.io.IOException * communications error prevented obtaining the header. * @since 4.7 */ @@ -265,7 +269,7 @@ public class HttpSupport { * @param u * location of the server caller wants to talk to. * @return proxy to communicate with the supplied URL. - * @throws ConnectException + * @throws java.net.ConnectException * the proxy could not be computed as the supplied URL could not * be read. This failure should never occur. */ @@ -285,7 +289,9 @@ public class HttpSupport { * Disable SSL and hostname verification for given HTTP connection * * @param conn - * @throws IOException + * a {@link org.eclipse.jgit.transport.http.HttpConnection} + * object. + * @throws java.io.IOException * @since 4.3 */ public static void disableSslVerify(HttpConnection conn) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/IO.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/IO.java index 6cff76cc21..f39d217863 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/IO.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/IO.java @@ -71,9 +71,9 @@ public class IO { * @param path * location of the file to read. * @return complete contents of the requested local file. - * @throws FileNotFoundException + * @throws java.io.FileNotFoundException * the file does not exist. - * @throws IOException + * @throws java.io.IOException * the file exists, but its contents cannot be read. */ public static final byte[] readFully(final File path) @@ -91,9 +91,9 @@ public class IO { * only the first limit number of bytes are returned * @return complete contents of the requested local file. If the contents * exceeds the limit, then only the limit is returned. - * @throws FileNotFoundException + * @throws java.io.FileNotFoundException * the file does not exist. - * @throws IOException + * @throws java.io.IOException * the file exists, but its contents cannot be read. */ public static final byte[] readSome(final File path, final int limit) @@ -131,9 +131,9 @@ public class IO { * maximum number of bytes to read, if the file is larger than * this limit an IOException is thrown. * @return complete contents of the requested local file. - * @throws FileNotFoundException + * @throws java.io.FileNotFoundException * the file does not exist. - * @throws IOException + * @throws java.io.IOException * the file exists, but its contents cannot be read. */ public static final byte[] readFully(final File path, final int max) @@ -199,7 +199,7 @@ public class IO { * on obtaining the underlying array for efficient data access. If * {@code sizeHint} was too large, the array may be over-allocated, * resulting in {@code limit() < array().length}. - * @throws IOException + * @throws java.io.IOException * there was an error reading from the stream. */ public static ByteBuffer readWholeStream(InputStream in, int sizeHint) @@ -238,7 +238,7 @@ public class IO { * number of bytes that must be read. * @throws EOFException * the stream ended before dst was fully populated. - * @throws IOException + * @throws java.io.IOException * there was an error reading from the stream. */ public static void readFully(final InputStream fd, final byte[] dst, @@ -264,7 +264,7 @@ public class IO { * @param len * number of bytes that should be read. * @return number of bytes actually read. - * @throws IOException + * @throws java.io.IOException * there was an error reading from the channel. */ public static int read(ReadableByteChannel channel, byte[] dst, int off, @@ -293,7 +293,7 @@ public class IO { * @param off * position within the buffer to start writing to. * @return number of bytes in buffer or stream, whichever is shortest - * @throws IOException + * @throws java.io.IOException * there was an error reading from the stream. */ public static int readFully(InputStream fd, byte[] dst, int off) @@ -322,7 +322,7 @@ public class IO { * @throws EOFException * the stream ended before the requested number of bytes were * skipped. - * @throws IOException + * @throws java.io.IOException * there was an error reading from the stream. */ public static void skipFully(final InputStream fd, long toSkip) @@ -384,7 +384,7 @@ public class IO { * hint for buffer sizing; 0 or negative for default. * @return the next line from the input, always ending in {@code \n} unless * EOF was reached. - * @throws IOException + * @throws java.io.IOException * there was an error reading from the stream. * @since 4.1 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/IntList.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/IntList.java index 0a3c846a0e..24038f0976 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/IntList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/IntList.java @@ -44,13 +44,17 @@ package org.eclipse.jgit.util; -/** A more efficient List<Integer> using a primitive integer array. */ +/** + * A more efficient List<Integer> using a primitive integer array. + */ public class IntList { private int[] entries; private int count; - /** Create an empty list with a default capacity. */ + /** + * Create an empty list with a default capacity. + */ public IntList() { this(10); } @@ -65,7 +69,11 @@ public class IntList { entries = new int[capacity]; } - /** @return number of entries in this list */ + /** + * Get number of entries in this list. + * + * @return number of entries in this list. + */ public int size() { return count; } @@ -86,10 +94,12 @@ public class IntList { } /** + * Get the value at the specified index + * * @param i * index to read, must be in the range [0, {@link #size()}). * @return the number at the specified index - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * the index outside the valid range */ public int get(final int i) { @@ -98,7 +108,9 @@ public class IntList { return entries[i]; } - /** Empty this list */ + /** + * Empty this list + */ public void clear() { count = 0; } @@ -153,6 +165,7 @@ public class IntList { entries = n; } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/LongList.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/LongList.java index e3639f5c65..404594cf79 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/LongList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/LongList.java @@ -46,13 +46,17 @@ package org.eclipse.jgit.util; import java.util.Arrays; -/** A more efficient List<Long> using a primitive long array. */ +/** + * A more efficient List<Long> using a primitive long array. + */ public class LongList { private long[] entries; private int count; - /** Create an empty list with a default capacity. */ + /** + * Create an empty list with a default capacity. + */ public LongList() { this(10); } @@ -67,16 +71,22 @@ public class LongList { entries = new long[capacity]; } - /** @return number of entries in this list */ + /** + * Get number of entries in this list + * + * @return number of entries in this list + */ public int size() { return count; } /** + * Get the value at the specified index + * * @param i * index to read, must be in the range [0, {@link #size()}). * @return the number at the specified index - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * the index outside the valid range */ public long get(final int i) { @@ -99,7 +109,9 @@ public class LongList { return false; } - /** Empty this list */ + /** + * Clear this list + */ public void clear() { count = 0; } @@ -148,7 +160,9 @@ public class LongList { add(val); } - /** Sort the list of longs according to their natural ordering. */ + /** + * Sort the list of longs according to their natural ordering. + */ public void sort() { Arrays.sort(entries, 0, count); } @@ -159,6 +173,7 @@ public class LongList { entries = n; } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/LongMap.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/LongMap.java index 7b0b0c728a..e00289247e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/LongMap.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/LongMap.java @@ -61,13 +61,17 @@ public class LongMap { /** Next {@link #size} to trigger a {@link #grow()}. */ private int growAt; - /** Initialize an empty LongMap. */ + /** + * Initialize an empty LongMap. + */ public LongMap() { table = createArray(64); growAt = (int) (table.length * LOAD_FACTOR); } /** + * Whether {@code key} is present in the map. + * * @param key * the key to find. * @return {@code true} if {@code key} is present in the map. @@ -77,9 +81,11 @@ public class LongMap { } /** + * Get value for this {@code key} + * * @param key * the key to find. - * @return stored value of the key, or {@code null}. + * @return stored value for this key, or {@code null}. */ public V get(long key) { for (Node n = table[index(key)]; n != null; n = n.next) { @@ -90,6 +96,8 @@ public class LongMap { } /** + * Remove an entry from the map + * * @param key * key to remove from the map. * @return old value of the key, or {@code null}. @@ -113,6 +121,8 @@ public class LongMap { } /** + * Put a new entry into the map + * * @param key * key to store {@code value} under. * @param value diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/MutableInteger.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/MutableInteger.java index cbe321086c..8cee9f9608 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/MutableInteger.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/MutableInteger.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.util; -/** A boxed integer that can be modified. */ +/** + * A boxed integer that can be modified. + */ public final class MutableInteger { /** Current value of this boxed value. */ public int value; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/NB.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/NB.java index 471a4998d7..8ad6aa0ad8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/NB.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/NB.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.util; -/** Conversion utilities for network byte order handling. */ +/** + * Conversion utilities for network byte order handling. + */ public final class NB { /** * Compare a 32 bit unsigned integer stored in a 32 bit signed integer. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/ProcessResult.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/ProcessResult.java index 77c9608c79..9267a325f4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/ProcessResult.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/ProcessResult.java @@ -86,6 +86,8 @@ public class ProcessResult { } /** + *

      Constructor for ProcessResult.

      + * * @param exitCode * Exit code of the process. * @param status @@ -97,6 +99,8 @@ public class ProcessResult { } /** + * Get exit code of the process. + * * @return The exit code of the process. */ public int getExitCode() { @@ -104,6 +108,8 @@ public class ProcessResult { } /** + * Get the status of the process' execution. + * * @return The status of the process' execution. */ public Status getStatus() { @@ -111,6 +117,8 @@ public class ProcessResult { } /** + * Whether the execution occurred and resulted in an error + * * @return true if the execution occurred and resulted in a * return code different from 0, false otherwise. * @since 4.0 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/QuotedString.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/QuotedString.java index 57dfb85903..77bc2495fb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/QuotedString.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/QuotedString.java @@ -47,7 +47,9 @@ import java.util.Arrays; import org.eclipse.jgit.lib.Constants; -/** Utility functions related to quoted string handling. */ +/** + * Utility functions related to quoted string handling. + */ public abstract class QuotedString { /** Quoting style that obeys the rules Git applies to file names */ public static final GitPathStyle GIT_PATH = new GitPathStyle(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawCharSequence.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawCharSequence.java index e85bd659b4..23ee9d0d64 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawCharSequence.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawCharSequence.java @@ -74,21 +74,25 @@ public final class RawCharSequence implements CharSequence { endPtr = end; } + /** {@inheritDoc} */ @Override public char charAt(final int index) { return (char) (buffer[startPtr + index] & 0xff); } + /** {@inheritDoc} */ @Override public int length() { return endPtr - startPtr; } + /** {@inheritDoc} */ @Override public CharSequence subSequence(final int start, final int end) { return new RawCharSequence(buffer, startPtr + start, startPtr + end); } + /** {@inheritDoc} */ @Override public String toString() { final int n = length(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java index ad138bbf18..014c7727a8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java @@ -66,7 +66,9 @@ import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.PersonIdent; -/** Handy utility functions to parse raw object contents. */ +/** + * Handy utility functions to parse raw object contents. + */ public final class RawParseUtils { /** * UTF-8 charset constant. @@ -306,7 +308,7 @@ public final class RawParseUtils { * @param p * first position within the buffer to parse. * @return the integer value. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * if the string is not hex formatted. */ public static final int parseHexInt16(final byte[] bs, final int p) { @@ -336,7 +338,7 @@ public final class RawParseUtils { * @param p * first position within the buffer to parse. * @return the integer value. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * if the string is not hex formatted. */ public static final int parseHexInt32(final byte[] bs, final int p) { @@ -377,7 +379,7 @@ public final class RawParseUtils { * @param p * first position within the buffer to parse. * @return the integer value. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * if the string is not hex formatted. * @since 4.3 */ @@ -437,7 +439,7 @@ public final class RawParseUtils { * @param digit * hex character to parse. * @return numeric value, in the range 0-15. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * if the input digit is not a valid hex digit. */ public static final int parseHexInt4(final byte digit) { @@ -610,7 +612,7 @@ public final class RawParseUtils { * Index the region between [ptr, end) to find line starts. *

      * The returned list is 1 indexed. Index 0 contains - * {@link Integer#MIN_VALUE} to pad the list out. + * {@link java.lang.Integer#MIN_VALUE} to pad the list out. *

      * Using a 1 indexed list means that line numbers can be directly accessed * from the list, so list.get(1) (aka get line 1) returns @@ -619,8 +621,8 @@ public final class RawParseUtils { * The last element (index map.size()-1) always contains * end. *

      - * If the data contains a '\0' anywhere, the whole region is considered binary - * and a LineMap corresponding to a single line is returned. + * If the data contains a '\0' anywhere, the whole region is considered + * binary and a LineMap corresponding to a single line is returned. *

      * * @param buf @@ -1076,7 +1078,7 @@ public final class RawParseUtils { * data from. * @return a string representation of the range [start,end), * after decoding the region through the specified character set. - * @throws CharacterCodingException + * @throws java.nio.charset.CharacterCodingException * the input is not in any of the tested character sets. */ public static String decodeNoFallback(final Charset cs, @@ -1222,13 +1224,15 @@ public final class RawParseUtils { } /** + * Get last index of {@code ch} in raw, trimming spaces. + * * @param raw * buffer to scan. * @param ch * character to find. * @param pos * starting position. - * @return last index of ch in raw, trimming spaces. + * @return last index of {@code ch} in raw, trimming spaces. * @since 4.1 */ public static int lastIndexOfTrim(byte[] raw, char ch, int pos) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawSubStringPattern.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawSubStringPattern.java index bc101bd7d7..a8f9bc72eb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawSubStringPattern.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawSubStringPattern.java @@ -131,6 +131,7 @@ public class RawSubStringPattern { return needleString; } + /** {@inheritDoc} */ @Override public String toString() { return pattern(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RefList.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RefList.java index ce4b7c7507..639c353621 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RefList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RefList.java @@ -71,9 +71,9 @@ public class RefList implements Iterable { private static final RefList EMPTY = new RefList<>(new Ref[0], 0); /** + * Create an empty unmodifiable reference list. + * * @return an empty unmodifiable reference list. - * @param - * the type of reference being stored in the collection. */ @SuppressWarnings("unchecked") public static RefList emptyList() { @@ -100,6 +100,7 @@ public class RefList implements Iterable { this.cnt = src.cnt; } + /** {@inheritDoc} */ @Override public Iterator iterator() { return new Iterator() { @@ -124,18 +125,30 @@ public class RefList implements Iterable { }; } - /** @return this cast as an immutable, standard {@link java.util.List}. */ + /** + * Cast {@code this} as an immutable, standard {@link java.util.List}. + * + * @return {@code this} as an immutable, standard {@link java.util.List}. + */ public final List asList() { final List r = Arrays.asList(list).subList(0, cnt); return Collections.unmodifiableList(r); } - /** @return number of items in this list. */ + /** + * Get number of items in this list. + * + * @return number of items in this list. + */ public final int size() { return cnt; } - /** @return true if the size of this list is 0. */ + /** + * Get if this list is empty. + * + * @return true if the size of this list is 0. + */ public final boolean isEmpty() { return cnt == 0; } @@ -303,6 +316,7 @@ public class RefList implements Iterable { return add(idx, ref); } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RefMap.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RefMap.java index 510e81821e..c1aaecfd91 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RefMap.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RefMap.java @@ -59,17 +59,19 @@ import org.eclipse.jgit.lib.RefComparator; * Specialized Map to present a {@code RefDatabase} namespace. *

      * Although not declared as a {@link java.util.SortedMap}, iterators from this - * map's projections always return references in {@link RefComparator} ordering. - * The map's internal representation is a sorted array of {@link Ref} objects, + * map's projections always return references in + * {@link org.eclipse.jgit.lib.RefComparator} ordering. The map's internal + * representation is a sorted array of {@link org.eclipse.jgit.lib.Ref} objects, * which means lookup and replacement is O(log N), while insertion and removal * can be as expensive as O(N + log N) while the list expands or contracts. * Since this is not a general map implementation, all entries must be keyed by * the reference name. *

      * This class is really intended as a helper for {@code RefDatabase}, which - * needs to perform a merge-join of three sorted {@link RefList}s in order to - * present the unified namespace of the packed-refs file, the loose refs/ - * directory tree, and the resolved form of any symbolic references. + * needs to perform a merge-join of three sorted + * {@link org.eclipse.jgit.util.RefList}s in order to present the unified + * namespace of the packed-refs file, the loose refs/ directory tree, and the + * resolved form of any symbolic references. */ public class RefMap extends AbstractMap { /** @@ -109,7 +111,9 @@ public class RefMap extends AbstractMap { private Set> entrySet; - /** Construct an empty map with a small initial capacity. */ + /** + * Construct an empty map with a small initial capacity. + */ public RefMap() { prefix = ""; //$NON-NLS-1$ packed = RefList.emptyList(); @@ -145,11 +149,13 @@ public class RefMap extends AbstractMap { this.resolved = (RefList) resolved; } + /** {@inheritDoc} */ @Override public boolean containsKey(Object name) { return get(name) != null; } + /** {@inheritDoc} */ @Override public Ref get(Object key) { String name = toRefName((String) key); @@ -161,6 +167,7 @@ public class RefMap extends AbstractMap { return ref; } + /** {@inheritDoc} */ @Override public Ref put(final String keyName, Ref value) { String name = toRefName(keyName); @@ -189,6 +196,7 @@ public class RefMap extends AbstractMap { } } + /** {@inheritDoc} */ @Override public Ref remove(Object key) { String name = toRefName((String) key); @@ -212,11 +220,13 @@ public class RefMap extends AbstractMap { return res; } + /** {@inheritDoc} */ @Override public boolean isEmpty() { return entrySet().isEmpty(); } + /** {@inheritDoc} */ @Override public Set> entrySet() { if (entrySet == null) { @@ -258,6 +268,7 @@ public class RefMap extends AbstractMap { return entrySet; } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RelativeDateFormatter.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RelativeDateFormatter.java index a5df66e99c..83c60c63bc 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RelativeDateFormatter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RelativeDateFormatter.java @@ -67,10 +67,14 @@ public class RelativeDateFormatter { final static long YEAR_IN_MILLIS = 365 * DAY_IN_MILLIS; /** + * Get age of given {@link java.util.Date} compared to now formatted in the + * same relative format as returned by {@code git log --relative-date} + * * @param when - * {@link Date} to format - * @return age of given {@link Date} compared to now formatted in the same - * relative format as returned by {@code git log --relative-date} + * {@link java.util.Date} to format + * @return age of given {@link java.util.Date} compared to now formatted in + * the same relative format as returned by + * {@code git log --relative-date} */ @SuppressWarnings("boxing") public static String format(Date when) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/StringUtils.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/StringUtils.java index 2bfeaf1166..fdb6600d01 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/StringUtils.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/StringUtils.java @@ -48,7 +48,9 @@ import java.util.Collection; import org.eclipse.jgit.internal.JGitText; -/** Miscellaneous string comparison utility methods. */ +/** + * Miscellaneous string comparison utility methods. + */ public final class StringUtils { private static final char[] LC; @@ -102,10 +104,12 @@ public final class StringUtils { * *

      * Capitalizes a String changing the first letter to title case as per - * {@link Character#toTitleCase(char)}. No other letters are changed. + * {@link java.lang.Character#toTitleCase(char)}. No other letters are + * changed. *

      * - * A null input String returns null.

      + * A null input String returns null. + *

      * * @param str * the String to capitalize, may be null @@ -156,9 +160,8 @@ public final class StringUtils { * first string to compare. * @param b * second string to compare. - * @return negative, zero or positive if a sorts before, is equal to, or - * sorts after b. * @since 2.0 + * @return an int. */ public static int compareIgnoreCase(String a, String b) { for (int i = 0; i < a.length() && i < b.length(); i++) { @@ -179,9 +182,8 @@ public final class StringUtils { * first string to compare. * @param b * second string to compare. - * @return negative, zero or positive if a sorts before, is equal to, or - * sorts after b. * @since 2.0 + * @return an int. */ public static int compareWithCase(String a, String b) { for (int i = 0; i < a.length() && i < b.length(); i++) { @@ -199,7 +201,7 @@ public final class StringUtils { * @param stringValue * the string to parse. * @return the boolean interpretation of {@code value}. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * if {@code value} is not recognized as one of the standard * boolean names. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/SystemReader.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/SystemReader.java index 2cd8035854..96a796cbdc 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/SystemReader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/SystemReader.java @@ -151,12 +151,18 @@ public abstract class SystemReader { private static SystemReader INSTANCE = DEFAULT; - /** @return the live instance to read system properties. */ + /** + * Get time since epoch, with up to millisecond resolution. + * + * @return time since epoch, with up to millisecond resolution. + */ public static SystemReader getInstance() { return INSTANCE; } /** + * Set the new instance to use when accessing properties. + * * @param newReader * the new instance to use when accessing properties, or null for * the default instance. @@ -201,18 +207,26 @@ public abstract class SystemReader { public abstract String getHostname(); /** - * @param variable system variable to read + * Get value of the system variable + * + * @param variable + * system variable to read * @return value of the system variable */ public abstract String getenv(String variable); /** - * @param key of the system property to read + * Get value of the system property + * + * @param key + * of the system property to read * @return value of the system property */ public abstract String getProperty(String key); /** + * Open the git configuration found in the user home + * * @param parent * a config with values not found directly in the returned config * @param fs @@ -223,6 +237,8 @@ public abstract class SystemReader { public abstract FileBasedConfig openUserConfig(Config parent, FS fs); /** + * Open the gitonfig configuration found in the system-wide "etc" directory + * * @param parent * a config with values not found directly in the returned * config. Null is a reasonable value here. @@ -235,11 +251,15 @@ public abstract class SystemReader { public abstract FileBasedConfig openSystemConfig(Config parent, FS fs); /** + * Get the current system time + * * @return the current system time */ public abstract long getCurrentTime(); /** + * Get clock instance preferred by this system. + * * @return clock instance preferred by this system. * @since 4.6 */ @@ -248,12 +268,17 @@ public abstract class SystemReader { } /** - * @param when TODO + * Get the local time zone + * + * @param when + * a system timestamp * @return the local time zone */ public abstract int getTimezone(long when); /** + * Get system time zone, possibly mocked for testing + * * @return system time zone, possibly mocked for testing * @since 1.2 */ @@ -262,6 +287,8 @@ public abstract class SystemReader { } /** + * Get the locale to use + * * @return the locale to use * @since 1.2 */ @@ -274,7 +301,7 @@ public abstract class SystemReader { * * @param pattern * the pattern as defined in - * {@link SimpleDateFormat#SimpleDateFormat(String)} + * {@link java.text.SimpleDateFormat#SimpleDateFormat(String)} * @return the simple date format * @since 2.0 */ @@ -287,7 +314,7 @@ public abstract class SystemReader { * * @param pattern * the pattern as defined in - * {@link SimpleDateFormat#SimpleDateFormat(String)} + * {@link java.text.SimpleDateFormat#SimpleDateFormat(String)} * @param locale * locale to be used for the {@code SimpleDateFormat} * @return the simple date format @@ -302,10 +329,10 @@ public abstract class SystemReader { * * @param dateStyle * the date style as specified in - * {@link DateFormat#getDateTimeInstance(int, int)} + * {@link java.text.DateFormat#getDateTimeInstance(int, int)} * @param timeStyle * the time style as specified in - * {@link DateFormat#getDateTimeInstance(int, int)} + * {@link java.text.DateFormat#getDateTimeInstance(int, int)} * @return the date format * @since 2.0 */ @@ -314,7 +341,9 @@ public abstract class SystemReader { } /** - * @return true if we are running on a Windows. + * Whether we are running on Windows. + * + * @return true if we are running on Windows. */ public boolean isWindows() { if (isWindows == null) { @@ -325,6 +354,8 @@ public abstract class SystemReader { } /** + * Whether we are running on Mac OS X + * * @return true if we are running on Mac OS X */ public boolean isMacOS() { @@ -351,7 +382,7 @@ public abstract class SystemReader { * Scans a multi-directory path string such as {@code "src/main.c"}. * * @param path path string to scan. - * @throws CorruptObjectException path is invalid. + * @throws org.eclipse.jgit.errors.CorruptObjectException path is invalid. * @since 3.6 */ public void checkPath(String path) throws CorruptObjectException { @@ -365,7 +396,7 @@ public abstract class SystemReader { * * @param path * path string to scan. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * path is invalid. * @since 4.2 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/TemporaryBuffer.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/TemporaryBuffer.java index e3f1916f43..31abb7c173 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/TemporaryBuffer.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/TemporaryBuffer.java @@ -114,6 +114,7 @@ public abstract class TemporaryBuffer extends OutputStream { reset(); } + /** {@inheritDoc} */ @Override public void write(final int b) throws IOException { if (overflow != null) { @@ -134,6 +135,7 @@ public abstract class TemporaryBuffer extends OutputStream { s.buffer[s.count++] = (byte) b; } + /** {@inheritDoc} */ @Override public void write(final byte[] b, int off, int len) throws IOException { if (overflow == null) { @@ -162,7 +164,7 @@ public abstract class TemporaryBuffer extends OutputStream { /** * Dumps the entire buffer into the overflow stream, and flushes it. * - * @throws IOException + * @throws java.io.IOException * the overflow stream cannot be started, or the buffer contents * cannot be written to it, or it failed to flush. */ @@ -177,7 +179,7 @@ public abstract class TemporaryBuffer extends OutputStream { * * @param in * the stream to read from, until EOF is reached. - * @throws IOException + * @throws java.io.IOException * an error occurred reading from the input stream, or while * writing to a local temporary file. */ @@ -227,10 +229,8 @@ public abstract class TemporaryBuffer extends OutputStream { * The buffer is only complete after {@link #close()} has been invoked. * * @return the complete byte array; length matches {@link #length()}. - * @throws IOException + * @throws java.io.IOException * an error occurred reading from a local temporary file - * @throws OutOfMemoryError - * the buffer cannot fit in memory */ public byte[] toByteArray() throws IOException { final long len = length(); @@ -253,13 +253,9 @@ public abstract class TemporaryBuffer extends OutputStream { * * @param limit * the maximum number of bytes to be returned - * * @return the byte array limited to {@code limit} bytes. - * @throws IOException + * @throws java.io.IOException * an error occurred reading from a local temporary file - * @throws OutOfMemoryError - * the buffer cannot fit in memory - * * @since 4.2 */ public byte[] toByteArray(int limit) throws IOException { @@ -288,7 +284,7 @@ public abstract class TemporaryBuffer extends OutputStream { * if not null progress updates are sent here. Caller should * initialize the task and the number of work units to * {@link #length()}/1024. - * @throws IOException + * @throws java.io.IOException * an error occurred reading from a temporary file on the local * system, or writing to the output stream. */ @@ -310,14 +306,16 @@ public abstract class TemporaryBuffer extends OutputStream { * * @return a stream to read from the buffer. The caller must close the * stream when it is no longer useful. - * @throws IOException + * @throws java.io.IOException * an error occurred opening the temporary file. */ public InputStream openInputStream() throws IOException { return new BlockInputStream(); } - /** Reset this buffer for reuse, purging all buffered content. */ + /** + * Reset this buffer for reuse, purging all buffered content. + */ public void reset() { if (overflow != null) { destroy(); @@ -334,7 +332,7 @@ public abstract class TemporaryBuffer extends OutputStream { * * @return the output stream to receive the buffered content, followed by * the remaining output. - * @throws IOException + * @throws java.io.IOException * the buffer cannot create the overflow stream. */ protected abstract OutputStream overflow() throws IOException; @@ -363,6 +361,7 @@ public abstract class TemporaryBuffer extends OutputStream { overflow.write(last.buffer, 0, last.count); } + /** {@inheritDoc} */ @Override public void close() throws IOException { if (overflow != null) { @@ -374,7 +373,9 @@ public abstract class TemporaryBuffer extends OutputStream { } } - /** Clear this buffer so it has no data, and cannot be used again. */ + /** + * Clear this buffer so it has no data, and cannot be used again. + */ public void destroy() { blocks = null; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFInputStream.java index 30f9ce95fc..45668255e5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFInputStream.java @@ -91,12 +91,14 @@ public class AutoCRLFInputStream extends InputStream { this.detectBinary = detectBinary; } + /** {@inheritDoc} */ @Override public int read() throws IOException { final int read = read(single, 0, 1); return read == 1 ? single[0] & 0xff : -1; } + /** {@inheritDoc} */ @Override public int read(byte[] bs, final int off, final int len) throws IOException { if (len == 0) @@ -135,6 +137,7 @@ public class AutoCRLFInputStream extends InputStream { return n; } + /** {@inheritDoc} */ @Override public void close() throws IOException { in.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFOutputStream.java index 3a72f7e1dc..e764389ac8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFOutputStream.java @@ -75,14 +75,18 @@ public class AutoCRLFOutputStream extends OutputStream { private boolean isBinary; /** - * @param out + *

      Constructor for AutoCRLFOutputStream.

      + * + * @param out a {@link java.io.OutputStream} object. */ public AutoCRLFOutputStream(OutputStream out) { this(out, true); } /** - * @param out + *

      Constructor for AutoCRLFOutputStream.

      + * + * @param out a {@link java.io.OutputStream} object. * @param detectBinary * whether binaries should be detected * @since 4.3 @@ -92,12 +96,14 @@ public class AutoCRLFOutputStream extends OutputStream { this.detectBinary = detectBinary; } + /** {@inheritDoc} */ @Override public void write(int b) throws IOException { onebytebuf[0] = (byte) b; write(onebytebuf, 0, 1); } + /** {@inheritDoc} */ @Override public void write(byte[] b) throws IOException { int overflow = buffer(b, 0, b.length); @@ -105,6 +111,7 @@ public class AutoCRLFOutputStream extends OutputStream { write(b, b.length - overflow, overflow); } + /** {@inheritDoc} */ @Override public void write(byte[] b, final int startOff, final int startLen) throws IOException { @@ -166,6 +173,7 @@ public class AutoCRLFOutputStream extends OutputStream { write(binbuf, 0, cachedLen); } + /** {@inheritDoc} */ @Override public void flush() throws IOException { if (binbufcnt <= binbuf.length) @@ -174,6 +182,7 @@ public class AutoCRLFOutputStream extends OutputStream { out.flush(); } + /** {@inheritDoc} */ @Override public void close() throws IOException { flush(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFInputStream.java index 6e33f99127..06f83f3ed9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFInputStream.java @@ -125,12 +125,14 @@ public class AutoLFInputStream extends InputStream { this.abortIfBinary = abortIfBinary; } + /** {@inheritDoc} */ @Override public int read() throws IOException { final int read = read(single, 0, 1); return read == 1 ? single[0] & 0xff : -1; } + /** {@inheritDoc} */ @Override public int read(byte[] bs, final int off, final int len) throws IOException { @@ -171,13 +173,16 @@ public class AutoLFInputStream extends InputStream { } /** - * @return true if the stream has detected as a binary so far + * Whether the stream has detected as a binary so far. + * + * @return true if the stream has detected as a binary so far. * @since 3.3 */ public boolean isBinary() { return isBinary; } + /** {@inheritDoc} */ @Override public void close() throws IOException { in.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFOutputStream.java index c932b00f3c..32226c4af4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFOutputStream.java @@ -76,14 +76,24 @@ public class AutoLFOutputStream extends OutputStream { private boolean isBinary; /** + *

      + * Constructor for AutoLFOutputStream. + *

      + * * @param out + * an {@link java.io.OutputStream} object. */ public AutoLFOutputStream(OutputStream out) { this(out, true); } /** + *

      + * Constructor for AutoLFOutputStream. + *

      + * * @param out + * an {@link java.io.OutputStream} object. * @param detectBinary * whether binaries should be detected */ @@ -92,12 +102,14 @@ public class AutoLFOutputStream extends OutputStream { this.detectBinary = detectBinary; } + /** {@inheritDoc} */ @Override public void write(int b) throws IOException { onebytebuf[0] = (byte) b; write(onebytebuf, 0, 1); } + /** {@inheritDoc} */ @Override public void write(byte[] b) throws IOException { int overflow = buffer(b, 0, b.length); @@ -106,6 +118,7 @@ public class AutoLFOutputStream extends OutputStream { } } + /** {@inheritDoc} */ @Override public void write(byte[] b, final int startOff, final int startLen) throws IOException { @@ -180,6 +193,7 @@ public class AutoLFOutputStream extends OutputStream { write(binbuf, 0, cachedLen); } + /** {@inheritDoc} */ @Override public void flush() throws IOException { if (binbufcnt <= binbuf.length) { @@ -188,6 +202,7 @@ public class AutoLFOutputStream extends OutputStream { out.flush(); } + /** {@inheritDoc} */ @Override public void close() throws IOException { flush(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/CountingOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/CountingOutputStream.java index ad6f1deceb..6fb1e6d698 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/CountingOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/CountingOutputStream.java @@ -46,7 +46,9 @@ package org.eclipse.jgit.util.io; import java.io.IOException; import java.io.OutputStream; -/** Counts the number of bytes written. */ +/** + * Counts the number of bytes written. + */ public class CountingOutputStream extends OutputStream { private final OutputStream out; private long cnt; @@ -61,28 +63,36 @@ public class CountingOutputStream extends OutputStream { this.out = out; } - /** @return current number of bytes written. */ + /** + * Get current number of bytes written. + * + * @return current number of bytes written. + */ public long getCount() { return cnt; } + /** {@inheritDoc} */ @Override public void write(int val) throws IOException { out.write(val); cnt++; } + /** {@inheritDoc} */ @Override public void write(byte[] buf, int off, int len) throws IOException { out.write(buf, off, len); cnt += len; } + /** {@inheritDoc} */ @Override public void flush() throws IOException { out.flush(); } + /** {@inheritDoc} */ @Override public void close() throws IOException { out.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/DisabledOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/DisabledOutputStream.java index 9ddf9b3c2b..ec3649523b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/DisabledOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/DisabledOutputStream.java @@ -48,7 +48,9 @@ import java.io.OutputStream; import org.eclipse.jgit.internal.JGitText; -/** An OutputStream which always throws IllegalStateExeption during write. */ +/** + * An OutputStream which always throws IllegalStateExeption during write. + */ public final class DisabledOutputStream extends OutputStream { /** The canonical instance which always throws IllegalStateException. */ public static final DisabledOutputStream INSTANCE = new DisabledOutputStream(); @@ -58,6 +60,7 @@ public final class DisabledOutputStream extends OutputStream { // more than one instance from being created. } + /** {@inheritDoc} */ @Override public void write(int b) throws IOException { // We shouldn't be writing output at this stage, there diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolCanonicalizingInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolCanonicalizingInputStream.java index ee729e893e..dd9a95306f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolCanonicalizingInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolCanonicalizingInputStream.java @@ -52,7 +52,7 @@ import java.io.InputStream; * Optionally, a binary check on the first 8000 bytes is performed and in case * of binary files, canonicalization is turned off (for the complete file). * - * @deprecated use {@link AutoLFInputStream} instead + * @deprecated use {@link org.eclipse.jgit.util.io.AutoLFInputStream} instead */ @Deprecated public class EolCanonicalizingInputStream extends AutoLFInputStream { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolStreamTypeUtil.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolStreamTypeUtil.java index 727c1f4ad6..e5b3fa55e2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolStreamTypeUtil.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolStreamTypeUtil.java @@ -46,14 +46,13 @@ import java.io.InputStream; import java.io.OutputStream; import org.eclipse.jgit.attributes.Attributes; -import org.eclipse.jgit.lib.Config; import org.eclipse.jgit.lib.CoreConfig.EolStreamType; import org.eclipse.jgit.treewalk.TreeWalk.OperationType; import org.eclipse.jgit.treewalk.WorkingTreeOptions; /** * Utility used to create input and output stream wrappers for - * {@link EolStreamType} + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} * * @since 4.3 */ @@ -73,16 +72,21 @@ public final class EolStreamTypeUtil { *
    • working tree .gitattributes
      • * * @param op - * is the {@link OperationType} of the current traversal + * is the + * {@link org.eclipse.jgit.treewalk.TreeWalk.OperationType} of + * the current traversal * @param options - * are the {@link Config} options with key - * {@link WorkingTreeOptions#KEY} + * are the {@link org.eclipse.jgit.lib.Config} options with key + * {@link org.eclipse.jgit.treewalk.WorkingTreeOptions#KEY} * @param attrs - * are the {@link Attributes} of the file for which the - * {@link EolStreamType} is to be detected - * - * @return the stream conversion {@link EolStreamType} to be performed for - * the selected {@link OperationType} + * are the {@link org.eclipse.jgit.attributes.Attributes} of the + * file for which the + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} is to be + * detected + * @return the stream conversion + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} to be + * performed for the selected + * {@link org.eclipse.jgit.treewalk.TreeWalk.OperationType} */ public static EolStreamType detectStreamType(OperationType op, WorkingTreeOptions options, Attributes attrs) { @@ -97,11 +101,15 @@ public final class EolStreamTypeUtil { } /** + * Wrap the input stream depending on + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} + * * @param in * original stream * @param conversion * to be performed - * @return the converted stream depending on {@link EolStreamType} + * @return the converted stream depending on + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} */ public static InputStream wrapInputStream(InputStream in, EolStreamType conversion) { @@ -120,11 +128,15 @@ public final class EolStreamTypeUtil { } /** + * Wrap the output stream depending on + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} + * * @param out * original stream * @param conversion * to be performed - * @return the converted stream depending on {@link EolStreamType} + * @return the converted stream depending on + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} */ public static OutputStream wrapOutputStream(OutputStream out, EolStreamType conversion) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/InterruptTimer.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/InterruptTimer.java index 0c5edb0070..f400e50cd3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/InterruptTimer.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/InterruptTimer.java @@ -88,7 +88,9 @@ public final class InterruptTimer { final AutoKiller autoKiller; - /** Create a new timer with a default thread name. */ + /** + * Create a new timer with a default thread name. + */ public InterruptTimer() { this("JGit-InterruptTimer"); //$NON-NLS-1$ } @@ -123,12 +125,16 @@ public final class InterruptTimer { state.begin(timeout); } - /** Disable the interrupt timer, as the operation is complete. */ + /** + * Disable the interrupt timer, as the operation is complete. + */ public void end() { state.end(); } - /** Shutdown the timer thread, and wait for it to terminate. */ + /** + * Shutdown the timer thread, and wait for it to terminate. + */ public void terminate() { state.terminate(); try { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/IsolatedOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/IsolatedOutputStream.java index 3598a7ba87..5e50995a2a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/IsolatedOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/IsolatedOutputStream.java @@ -91,11 +91,13 @@ public class IsolatedOutputStream extends OutputStream { new ArrayBlockingQueue(1), new NamedThreadFactory()); } + /** {@inheritDoc} */ @Override public void write(int ch) throws IOException { write(new byte[] { (byte) ch }, 0, 1); } + /** {@inheritDoc} */ @Override public void write(final byte[] buf, final int pos, final int cnt) throws IOException { @@ -109,6 +111,7 @@ public class IsolatedOutputStream extends OutputStream { }); } + /** {@inheritDoc} */ @Override public void flush() throws IOException { checkClosed(); @@ -121,6 +124,7 @@ public class IsolatedOutputStream extends OutputStream { }); } + /** {@inheritDoc} */ @Override public void close() throws IOException { if (!copier.isShutdown()) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/LimitedInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/LimitedInputStream.java index d74532fd4a..9ab2caa1ac 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/LimitedInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/LimitedInputStream.java @@ -51,13 +51,13 @@ import java.io.InputStream; import org.eclipse.jgit.internal.JGitText; /** - * Wraps a {@link InputStream}, limiting the number of bytes which can be - * read. + * Wraps a {@link java.io.InputStream}, limiting the number of bytes which can + * be read. * - * This class was copied and modifed from the Google Guava 16.0. Differently from - * the original Guava code, when a caller tries to read from this stream past - * the given limit and the wrapped stream hasn't yet reached its EOF this class - * will call the limitExceeded method instead of returning EOF. + * This class was copied and modifed from the Google Guava 16.0. Differently + * from the original Guava code, when a caller tries to read from this stream + * past the given limit and the wrapped stream hasn't yet reached its EOF this + * class will call the limitExceeded method instead of returning EOF. * * @since 3.3 */ @@ -80,18 +80,21 @@ public abstract class LimitedInputStream extends FilterInputStream { this.limit = limit; } + /** {@inheritDoc} */ @Override public int available() throws IOException { return (int) Math.min(in.available(), left); } // it's okay to mark even if mark isn't supported, as reset won't work + /** {@inheritDoc} */ @Override public synchronized void mark(int readLimit) { in.mark(readLimit); mark = left; } + /** {@inheritDoc} */ @Override public int read() throws IOException { if (left == 0) { @@ -107,6 +110,7 @@ public abstract class LimitedInputStream extends FilterInputStream { return result; } + /** {@inheritDoc} */ @Override public int read(byte[] b, int off, int len) throws IOException { if (left == 0) { @@ -123,6 +127,7 @@ public abstract class LimitedInputStream extends FilterInputStream { return result; } + /** {@inheritDoc} */ @Override public synchronized void reset() throws IOException { if (!in.markSupported()) @@ -135,6 +140,7 @@ public abstract class LimitedInputStream extends FilterInputStream { left = mark; } + /** {@inheritDoc} */ @Override public long skip(long n) throws IOException { n = Math.min(n, left); @@ -147,10 +153,11 @@ public abstract class LimitedInputStream extends FilterInputStream { * Called when trying to read past the given {@link #limit} and the wrapped * InputStream {@link #in} hasn't yet reached its EOF * - * @throws IOException - * subclasses can throw an IOException when the limit is exceeded. - * The throws IOException will be forwarded back to the caller of - * the read method which read the stream past the limit. + * @throws java.io.IOException + * subclasses can throw an {@link java.io.IOException} when the + * limit is exceeded. The throws java.io.IOException will be + * forwarded back to the caller of the read method which read + * the stream past the limit. */ protected abstract void limitExceeded() throws IOException; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/MessageWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/MessageWriter.java index a675360da1..94e5ef3d74 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/MessageWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/MessageWriter.java @@ -66,20 +66,24 @@ import org.eclipse.jgit.util.RawParseUtils; * {@link #toString()} returns all written data, after converting it to a String * under the assumption of UTF-8 encoding. *

      - * Internally {@link RawParseUtils#decode(byte[])} is used by {@code toString()} - * tries to work out a reasonably correct character set for the raw data. + * Internally {@link org.eclipse.jgit.util.RawParseUtils#decode(byte[])} is used + * by {@code toString()} tries to work out a reasonably correct character set + * for the raw data. */ public class MessageWriter extends Writer { private final ByteArrayOutputStream buf; private final OutputStreamWriter enc; - /** Create an empty writer. */ + /** + * Create an empty writer. + */ public MessageWriter() { buf = new ByteArrayOutputStream(); enc = new OutputStreamWriter(getRawStream(), Constants.CHARSET); } + /** {@inheritDoc} */ @Override public void write(char[] cbuf, int off, int len) throws IOException { synchronized (buf) { @@ -89,6 +93,9 @@ public class MessageWriter extends Writer { } /** + * Get the underlying byte stream that character writes to this writer drop + * into. + * * @return the underlying byte stream that character writes to this writer * drop into. Writes to this stream should should be in UTF-8. */ @@ -96,17 +103,20 @@ public class MessageWriter extends Writer { return buf; } + /** {@inheritDoc} */ @Override public void close() throws IOException { // Do nothing, we are buffered with no resources. } + /** {@inheritDoc} */ @Override public void flush() throws IOException { // Do nothing, we are buffered with no resources. } /** @return string version of all buffered data. */ + /** {@inheritDoc} */ @Override public String toString() { return RawParseUtils.decode(buf.toByteArray()); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/NullOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/NullOutputStream.java index 7b1e932738..f90f7e4164 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/NullOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/NullOutputStream.java @@ -57,16 +57,19 @@ public class NullOutputStream extends OutputStream { // more than one instance from being created. } + /** {@inheritDoc} */ @Override public void write(int b) { // Discard. } + /** {@inheritDoc} */ @Override public void write(byte[] buf) { // Discard. } + /** {@inheritDoc} */ @Override public void write(byte[] buf, int pos, int cnt) { // Discard. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/SafeBufferedOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/SafeBufferedOutputStream.java index 84c339889b..68b417e5d1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/SafeBufferedOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/SafeBufferedOutputStream.java @@ -46,11 +46,15 @@ import java.io.BufferedOutputStream; import java.io.OutputStream; /** + *

      SafeBufferedOutputStream class.

      + * * @deprecated use BufferedOutputStream in Java 8 and later. */ @Deprecated public class SafeBufferedOutputStream extends BufferedOutputStream { /** + *

      Constructor for SafeBufferedOutputStream.

      + * * @see BufferedOutputStream#BufferedOutputStream(OutputStream) * @param out * underlying output stream @@ -60,6 +64,8 @@ public class SafeBufferedOutputStream extends BufferedOutputStream { } /** + *

      Constructor for SafeBufferedOutputStream.

      + * * @see BufferedOutputStream#BufferedOutputStream(OutputStream, int) * @param out * underlying output stream diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/StreamCopyThread.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/StreamCopyThread.java index 7aba0a583d..5c1af9efad 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/StreamCopyThread.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/StreamCopyThread.java @@ -48,7 +48,9 @@ import java.io.InputStream; import java.io.InterruptedIOException; import java.io.OutputStream; -/** Thread to copy from an input stream to an output stream. */ +/** + * Thread to copy from an input stream to an output stream. + */ public class StreamCopyThread extends Thread { private static final int BUFFER_SIZE = 1024; @@ -98,7 +100,7 @@ public class StreamCopyThread extends Thread { * This method signals to the copy thread that it should stop as soon as * there is no more IO occurring. * - * @throws InterruptedException + * @throws java.lang.InterruptedException * the calling thread was interrupted. */ public void halt() throws InterruptedException { @@ -112,6 +114,7 @@ public class StreamCopyThread extends Thread { } } + /** {@inheritDoc} */ @Override public void run() { try { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TeeInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TeeInputStream.java index a7a0347401..dee4fe9e91 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TeeInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TeeInputStream.java @@ -47,15 +47,13 @@ import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; -import org.eclipse.jgit.util.TemporaryBuffer; - /** * Input stream that copies data read to another output stream. * - * This stream is primarily useful with a {@link TemporaryBuffer}, where any - * data read or skipped by the caller is also duplicated into the temporary - * buffer. Later the temporary buffer can then be used instead of the original - * source stream. + * This stream is primarily useful with a + * {@link org.eclipse.jgit.util.TemporaryBuffer}, where any data read or skipped + * by the caller is also duplicated into the temporary buffer. Later the + * temporary buffer can then be used instead of the original source stream. * * During close this stream copies any remaining data from the source stream * into the destination stream. @@ -74,13 +72,14 @@ public class TeeInputStream extends InputStream { * source stream to consume. * @param dst * destination to copy the source to as it is consumed. Typically - * this is a {@link TemporaryBuffer}. + * this is a {@link org.eclipse.jgit.util.TemporaryBuffer}. */ public TeeInputStream(InputStream src, OutputStream dst) { this.src = src; this.dst = dst; } + /** {@inheritDoc} */ @Override public int read() throws IOException { byte[] b = skipBuffer(); @@ -88,6 +87,7 @@ public class TeeInputStream extends InputStream { return n == 1 ? b[0] & 0xff : -1; } + /** {@inheritDoc} */ @Override public long skip(final long count) throws IOException { long skipped = 0; @@ -104,6 +104,7 @@ public class TeeInputStream extends InputStream { return skipped; } + /** {@inheritDoc} */ @Override public int read(byte[] b, int off, int len) throws IOException { if (len == 0) @@ -115,6 +116,7 @@ public class TeeInputStream extends InputStream { return n; } + /** {@inheritDoc} */ @Override public void close() throws IOException { byte[] b = skipBuffer(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/ThrowingPrintWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/ThrowingPrintWriter.java index 5eca0d99e1..caabcef574 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/ThrowingPrintWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/ThrowingPrintWriter.java @@ -64,7 +64,7 @@ public class ThrowingPrintWriter extends Writer { * Construct a JGitPrintWriter * * @param out - * the underlying {@link Writer} + * the underlying {@link java.io.Writer} */ public ThrowingPrintWriter(Writer out) { this.out = out; @@ -76,16 +76,19 @@ public class ThrowingPrintWriter extends Writer { }); } + /** {@inheritDoc} */ @Override public void write(char[] cbuf, int off, int len) throws IOException { out.write(cbuf, off, len); } + /** {@inheritDoc} */ @Override public void flush() throws IOException { out.flush(); } + /** {@inheritDoc} */ @Override public void close() throws IOException { out.close(); @@ -94,8 +97,8 @@ public class ThrowingPrintWriter extends Writer { /** * Print a string and terminate with a line feed. * - * @param s - * @throws IOException + * @param s a {@link java.lang.String} object. + * @throws java.io.IOException */ public void println(String s) throws IOException { print(s + LF); @@ -104,7 +107,7 @@ public class ThrowingPrintWriter extends Writer { /** * Print a platform dependent new line * - * @throws IOException + * @throws java.io.IOException */ public void println() throws IOException { print(LF); @@ -113,8 +116,8 @@ public class ThrowingPrintWriter extends Writer { /** * Print a char * - * @param value - * @throws IOException + * @param value a char. + * @throws java.io.IOException */ public void print(char value) throws IOException { print(String.valueOf(value)); @@ -124,7 +127,8 @@ public class ThrowingPrintWriter extends Writer { * Print an int as string * * @param value - * @throws IOException + * an int. + * @throws java.io.IOException */ public void print(int value) throws IOException { print(String.valueOf(value)); @@ -133,8 +137,8 @@ public class ThrowingPrintWriter extends Writer { /** * Print a long as string * - * @param value - * @throws IOException + * @param value a long. + * @throws java.io.IOException */ public void print(long value) throws IOException { print(String.valueOf(value)); @@ -143,8 +147,8 @@ public class ThrowingPrintWriter extends Writer { /** * Print a short as string * - * @param value - * @throws IOException + * @param value a short. + * @throws java.io.IOException */ public void print(short value) throws IOException { print(String.valueOf(value)); @@ -152,11 +156,13 @@ public class ThrowingPrintWriter extends Writer { /** * Print a formatted message according to - * {@link String#format(String, Object...)}. + * {@link java.lang.String#format(String, Object...)}. * * @param fmt + * a {@link java.lang.String} object. * @param args - * @throws IOException + * objects. + * @throws java.io.IOException */ public void format(String fmt, Object... args) throws IOException { print(String.format(fmt, args)); @@ -166,7 +172,8 @@ public class ThrowingPrintWriter extends Writer { * Print an object's toString representations * * @param any - * @throws IOException + * an object. + * @throws java.io.IOException */ public void print(Object any) throws IOException { out.write(String.valueOf(any)); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutInputStream.java index 1148895cc6..01b25195ff 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutInputStream.java @@ -51,7 +51,9 @@ import java.text.MessageFormat; import org.eclipse.jgit.internal.JGitText; -/** InputStream with a configurable timeout. */ +/** + * InputStream with a configurable timeout. + */ public class TimeoutInputStream extends FilterInputStream { private final InterruptTimer myTimer; @@ -72,12 +74,18 @@ public class TimeoutInputStream extends FilterInputStream { myTimer = timer; } - /** @return number of milliseconds before aborting a read. */ + /** + * Get number of milliseconds before aborting a read. + * + * @return number of milliseconds before aborting a read. + */ public int getTimeout() { return timeout; } /** + * Set number of milliseconds before aborting a read. + * * @param millis * number of milliseconds before aborting a read. Must be > 0. */ @@ -88,6 +96,7 @@ public class TimeoutInputStream extends FilterInputStream { timeout = millis; } + /** {@inheritDoc} */ @Override public int read() throws IOException { try { @@ -100,11 +109,13 @@ public class TimeoutInputStream extends FilterInputStream { } } + /** {@inheritDoc} */ @Override public int read(byte[] buf) throws IOException { return read(buf, 0, buf.length); } + /** {@inheritDoc} */ @Override public int read(byte[] buf, int off, int cnt) throws IOException { try { @@ -117,6 +128,7 @@ public class TimeoutInputStream extends FilterInputStream { } } + /** {@inheritDoc} */ @Override public long skip(long cnt) throws IOException { try { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutOutputStream.java index 9236d0eb51..ea40133383 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutOutputStream.java @@ -50,7 +50,9 @@ import java.text.MessageFormat; import org.eclipse.jgit.internal.JGitText; -/** OutputStream with a configurable timeout. */ +/** + * OutputStream with a configurable timeout. + */ public class TimeoutOutputStream extends OutputStream { private final OutputStream dst; @@ -73,14 +75,21 @@ public class TimeoutOutputStream extends OutputStream { myTimer = timer; } - /** @return number of milliseconds before aborting a write. */ + /** + * Get number of milliseconds before aborting a write. + * + * @return number of milliseconds before aborting a write. + */ public int getTimeout() { return timeout; } /** + * Set number of milliseconds before aborting a write. + * * @param millis - * number of milliseconds before aborting a write. Must be > 0. + * number of milliseconds before aborting a write. Must be > + * 0. */ public void setTimeout(final int millis) { if (millis < 0) @@ -89,6 +98,7 @@ public class TimeoutOutputStream extends OutputStream { timeout = millis; } + /** {@inheritDoc} */ @Override public void write(int b) throws IOException { try { @@ -101,11 +111,13 @@ public class TimeoutOutputStream extends OutputStream { } } + /** {@inheritDoc} */ @Override public void write(byte[] buf) throws IOException { write(buf, 0, buf.length); } + /** {@inheritDoc} */ @Override public void write(byte[] buf, int off, int len) throws IOException { try { @@ -118,6 +130,7 @@ public class TimeoutOutputStream extends OutputStream { } } + /** {@inheritDoc} */ @Override public void flush() throws IOException { try { @@ -130,6 +143,7 @@ public class TimeoutOutputStream extends OutputStream { } } + /** {@inheritDoc} */ @Override public void close() throws IOException { try { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/UnionInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/UnionInputStream.java index 1c46310ef5..51d3106aa5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/UnionInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/UnionInputStream.java @@ -58,7 +58,7 @@ import java.util.LinkedList; * Currently this stream does not support the mark/reset APIs. If mark and later * reset functionality is needed the caller should wrap this stream with a * {@link java.io.BufferedInputStream}. - * */ + */ public class UnionInputStream extends InputStream { private static final InputStream EOF = new InputStream() { @Override @@ -69,7 +69,9 @@ public class UnionInputStream extends InputStream { private final LinkedList streams = new LinkedList<>(); - /** Create an empty InputStream that is currently at EOF state. */ + /** + * Create an empty InputStream that is currently at EOF state. + */ public UnionInputStream() { // Do nothing. } @@ -122,6 +124,7 @@ public class UnionInputStream extends InputStream { return streams.isEmpty(); } + /** {@inheritDoc} */ @Override public int read() throws IOException { for (;;) { @@ -136,6 +139,7 @@ public class UnionInputStream extends InputStream { } } + /** {@inheritDoc} */ @Override public int read(byte[] b, int off, int len) throws IOException { if (len == 0) @@ -152,11 +156,13 @@ public class UnionInputStream extends InputStream { } } + /** {@inheritDoc} */ @Override public int available() throws IOException { return head().available(); } + /** {@inheritDoc} */ @Override public long skip(final long count) throws IOException { long skipped = 0; @@ -190,6 +196,7 @@ public class UnionInputStream extends InputStream { return skipped; } + /** {@inheritDoc} */ @Override public void close() throws IOException { IOException err = null; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/SHA1.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/SHA1.java index 544971199e..9fe01f1d8d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/SHA1.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/SHA1.java @@ -70,8 +70,8 @@ import org.slf4j.LoggerFactory; * sha1collisiondetection for more information. *

      * When detectCollision is true (default), this implementation throws - * {@link Sha1CollisionException} from any digest method if a potential - * collision was detected. + * {@link org.eclipse.jgit.util.sha1.Sha1CollisionException} from any digest + * method if a potential collision was detected. * * @since 4.7 */ @@ -85,7 +85,11 @@ public class SHA1 { DETECT_COLLISIONS = v != null ? Boolean.parseBoolean(v) : true; } - /** @return a new context to compute a SHA-1 hash of data. */ + /** + * Create a new context to compute a SHA-1 hash of data. + * + * @return a new context to compute a SHA-1 hash of data. + */ public static SHA1 newInstance() { return new SHA1(); } @@ -121,6 +125,7 @@ public class SHA1 { * {@code -Dorg.eclipse.jgit.util.sha1.detectCollision=true}. * * @param detect + * a boolean. * @return {@code this} */ public SHA1 setDetectCollision(boolean detect) { @@ -131,7 +136,7 @@ public class SHA1 { /** * Update the digest computation by adding a byte. * - * @param b + * @param b a byte. */ public void update(byte b) { int bufferLen = (int) (length & 63); @@ -503,7 +508,7 @@ public class SHA1 { * Once {@code digest()} is called, this instance should be discarded. * * @return the bytes for the resulting hash. - * @throws Sha1CollisionException + * @throws org.eclipse.jgit.util.sha1.Sha1CollisionException * if a collision was detected and safeHash is false. */ public byte[] digest() throws Sha1CollisionException { @@ -524,7 +529,7 @@ public class SHA1 { * Once {@code digest()} is called, this instance should be discarded. * * @return the ObjectId for the resulting hash. - * @throws Sha1CollisionException + * @throws org.eclipse.jgit.util.sha1.Sha1CollisionException * if a collision was detected and safeHash is false. */ public ObjectId toObjectId() throws Sha1CollisionException { @@ -539,7 +544,7 @@ public class SHA1 { * * @param id * destination to copy the digest to. - * @throws Sha1CollisionException + * @throws org.eclipse.jgit.util.sha1.Sha1CollisionException * if a collision was detected and safeHash is false. */ public void digest(MutableObjectId id) throws Sha1CollisionException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/Sha1CollisionException.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/Sha1CollisionException.java index be126a570a..dcefe95498 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/Sha1CollisionException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/Sha1CollisionException.java @@ -49,7 +49,8 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.ObjectId; /** - * Thrown by {@link SHA1} if it detects a likely hash collision. + * Thrown by {@link org.eclipse.jgit.util.sha1.SHA1} if it detects a likely hash + * collision. * * @since 4.7 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicClock.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicClock.java index 794d851903..1d4f5e8405 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicClock.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicClock.java @@ -44,7 +44,6 @@ package org.eclipse.jgit.util.time; import java.time.Duration; -import java.util.concurrent.TimeUnit; /** * A provider of time. @@ -53,7 +52,9 @@ import java.util.concurrent.TimeUnit; * source, such as the local system clock. *

      * MonotonicClocks provide the following behavior, with the assertion always - * being true if {@link ProposedTimestamp#blockUntil(Duration)} is used: + * being true if + * {@link org.eclipse.jgit.util.time.ProposedTimestamp#blockUntil(Duration)} is + * used: * * 

        *   MonotonicClock clk = ...;
@@ -83,14 +84,11 @@ public interface MonotonicClock {
 	 * by NTP) and return that proposal, concurrently sending network messages
 	 * to closely collaborating peers in the same cluster to also ensure their
 	 * system clocks are ahead of this time. In such an implementation the
-	 * {@link ProposedTimestamp#blockUntil(Duration)} method would wait for
-	 * replies from the peers indicating their own system clocks have moved past
-	 * the proposed time.
+	 * {@link org.eclipse.jgit.util.time.ProposedTimestamp#blockUntil(Duration)}
+	 * method would wait for replies from the peers indicating their own system
+	 * clocks have moved past the proposed time.
 	 *
-	 * @return "now". The value can be immediately accessed by
-	 *         {@link ProposedTimestamp#read(TimeUnit)} and friends, but the
-	 *         caller must use {@link ProposedTimestamp#blockUntil(Duration)} to
-	 *         ensure ordering holds.
+	 * @return a {@link org.eclipse.jgit.util.time.ProposedTimestamp} object.
 	 */
 	ProposedTimestamp propose();
 }
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicSystemClock.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicSystemClock.java
index a9f483063c..cce1e11f0d 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicSystemClock.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicSystemClock.java
@@ -51,7 +51,8 @@ import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicLong;
 
 /**
- * A {@link MonotonicClock} based on {@code System.currentTimeMillis}.
+ * A {@link org.eclipse.jgit.util.time.MonotonicClock} based on
+ * {@code System.currentTimeMillis}.
  *
  * @since 4.6
  */
@@ -69,6 +70,7 @@ public class MonotonicSystemClock implements MonotonicClock {
 		}
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public ProposedTimestamp propose() {
 		final long u = nowMicros();
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/time/ProposedTimestamp.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/time/ProposedTimestamp.java
index c09ab32b68..789950e2ca 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/util/time/ProposedTimestamp.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/time/ProposedTimestamp.java
@@ -55,7 +55,8 @@ import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
 /**
- * A timestamp generated by {@link MonotonicClock#propose()}.
+ * A timestamp generated by
+ * {@link org.eclipse.jgit.util.time.MonotonicClock#propose()}.
  * 
      
  * ProposedTimestamp implements AutoCloseable so that implementations can
  * release resources associated with obtaining certainty about time elapsing.
@@ -73,10 +74,10 @@ public abstract class ProposedTimestamp implements AutoCloseable {
 	 *            timestamps to wait on.
 	 * @param maxWait
 	 *            how long to wait for the timestamps.
-	 * @throws InterruptedException
+	 * @throws java.lang.InterruptedException
 	 *             current thread was interrupted before the waiting process
 	 *             completed normally.
-	 * @throws TimeoutException
+	 * @throws java.util.concurrent.TimeoutException
 	 *             the timeout was reached without the proposed timestamp become
 	 *             certainly in the past.
 	 */
@@ -121,31 +122,44 @@ public abstract class ProposedTimestamp implements AutoCloseable {
 	 * 
      
 	 * This method forces the caller to wait up to {@code timeout} for
 	 * {@code this} to pass sufficiently into the past such that the creating
-	 * {@link MonotonicClock} instance will not create an earlier timestamp.
+	 * {@link org.eclipse.jgit.util.time.MonotonicClock} instance will not
+	 * create an earlier timestamp.
 	 *
 	 * @param maxWait
 	 *            how long the implementation may block the caller.
-	 * @throws InterruptedException
+	 * @throws java.lang.InterruptedException
 	 *             current thread was interrupted before the waiting process
 	 *             completed normally.
-	 * @throws TimeoutException
+	 * @throws java.util.concurrent.TimeoutException
 	 *             the timeout was reached without the proposed timestamp
 	 *             becoming certainly in the past.
 	 */
 	public abstract void blockUntil(Duration maxWait)
 			throws InterruptedException, TimeoutException;
 
-	/** @return milliseconds since epoch; {@code read(MILLISECONDS}). */
+	/**
+	 * Get milliseconds since epoch; {@code read(MILLISECONDS}).
+	 *
+	 * @return milliseconds since epoch; {@code read(MILLISECONDS}).
+	 */
 	public long millis() {
 		return read(MILLISECONDS);
 	}
 
-	/** @return microseconds since epoch; {@code read(MICROSECONDS}). */
+	/**
+	 * Get microseconds since epoch; {@code read(MICROSECONDS}).
+	 *
+	 * @return microseconds since epoch; {@code read(MICROSECONDS}).
+	 */
 	public long micros() {
 		return read(MICROSECONDS);
 	}
 
-	/** @return time since epoch, with up to microsecond resolution. */
+	/**
+	 * Get time since epoch, with up to microsecond resolution.
+	 *
+	 * @return time since epoch, with up to microsecond resolution.
+	 */
 	public Instant instant() {
 		long usec = micros();
 		long secs = usec / 1000000L;
@@ -153,22 +167,35 @@ public abstract class ProposedTimestamp implements AutoCloseable {
 		return Instant.ofEpochSecond(secs, nanos);
 	}
 
-	/** @return time since epoch, with up to microsecond resolution. */
+	/**
+	 * Get time since epoch, with up to microsecond resolution.
+	 *
+	 * @return time since epoch, with up to microsecond resolution.
+	 */
 	public Timestamp timestamp() {
 		return Timestamp.from(instant());
 	}
 
-	/** @return time since epoch, with up to millisecond resolution. */
+	/**
+	 * Get time since epoch, with up to millisecond resolution.
+	 *
+	 * @return time since epoch, with up to millisecond resolution.
+	 */
 	public Date date() {
 		return new Date(millis());
 	}
 
-	/** Release resources allocated by this timestamp. */
+	/**
+	 * {@inheritDoc}
+	 * 
      
+	 * Release resources allocated by this timestamp.
+	 */
 	@Override
 	public void close() {
 		// Do nothing by default.
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		return instant().toString();
-- 
2.39.5