From 659cadf06d165f1a31a0466689d77dff7330f99d Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Wed, 29 May 2013 10:42:35 -0700 Subject: [PATCH] Add missing javadoc for archive code Document archive formats, the archive format interface, and the parameters of the GitAPIException constructors. Noticed by eclipse. Reported-by: Dani Megert Change-Id: I22b5f9d4c0358bbe867c1906feec7c279e214273 --- .../eclipse/jgit/archive/FormatActivator.java | 13 ++++++++ .../org/eclipse/jgit/archive/TarFormat.java | 3 ++ .../org/eclipse/jgit/archive/TgzFormat.java | 3 ++ .../org/eclipse/jgit/archive/TxzFormat.java | 3 ++ .../org/eclipse/jgit/archive/ZipFormat.java | 3 ++ .../org/eclipse/jgit/api/ArchiveCommand.java | 30 +++++++++++++++++++ .../jgit/api/errors/GitAPIException.java | 8 +++++ 7 files changed, 63 insertions(+) diff --git a/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/FormatActivator.java b/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/FormatActivator.java index f2f614025..c8ea28eef 100644 --- a/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/FormatActivator.java +++ b/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/FormatActivator.java @@ -56,10 +56,23 @@ import org.osgi.framework.BundleContext; * leaks). */ public class FormatActivator implements BundleActivator { + /** + * Registers all included archive formats by calling + * {@link #start()}. This method is called by the OSGi framework + * when the bundle is started. + * + * @param context unused + */ public void start(BundleContext context) { ArchiveFormats.registerAll(); } + /** + * Cleans up after {@link #start(BundleContext)} by calling + * {@link #stop()}. + * + * @param context unused + */ public void stop(BundleContext context) { ArchiveFormats.unregisterAll(); } diff --git a/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TarFormat.java b/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TarFormat.java index 2e5683c2b..3b27489e2 100644 --- a/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TarFormat.java +++ b/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TarFormat.java @@ -53,6 +53,9 @@ import org.eclipse.jgit.api.ArchiveCommand; import org.eclipse.jgit.lib.FileMode; import org.eclipse.jgit.lib.ObjectLoader; +/** + * Unix TAR format (ustar + old GNU long filename extension). + */ public class TarFormat implements ArchiveCommand.Format { public ArchiveOutputStream createArchiveOutputStream(OutputStream s) { return new TarArchiveOutputStream(s); diff --git a/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TgzFormat.java b/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TgzFormat.java index d68cb68e8..1c72bf8dc 100644 --- a/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TgzFormat.java +++ b/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TgzFormat.java @@ -51,6 +51,9 @@ import org.eclipse.jgit.api.ArchiveCommand; import org.eclipse.jgit.lib.FileMode; import org.eclipse.jgit.lib.ObjectLoader; +/** + * gzip-compressed tarball (tar.gz) format. + */ public class TgzFormat implements ArchiveCommand.Format { private final ArchiveCommand.Format tarFormat = new TarFormat(); diff --git a/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TxzFormat.java b/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TxzFormat.java index 622571f98..d1547c683 100644 --- a/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TxzFormat.java +++ b/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TxzFormat.java @@ -51,6 +51,9 @@ import org.eclipse.jgit.api.ArchiveCommand; import org.eclipse.jgit.lib.FileMode; import org.eclipse.jgit.lib.ObjectLoader; +/** + * Xz-compressed tar (tar.xz) format. + */ public class TxzFormat implements ArchiveCommand.Format { private final ArchiveCommand.Format tarFormat = new TarFormat(); diff --git a/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/ZipFormat.java b/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/ZipFormat.java index 19328775a..a0906d4dd 100644 --- a/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/ZipFormat.java +++ b/org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/ZipFormat.java @@ -52,6 +52,9 @@ import org.eclipse.jgit.api.ArchiveCommand; import org.eclipse.jgit.lib.FileMode; import org.eclipse.jgit.lib.ObjectLoader; +/** + * PKWARE's ZIP format. + */ public class ZipFormat implements ArchiveCommand.Format { public ArchiveOutputStream createArchiveOutputStream(OutputStream s) { return new ZipArchiveOutputStream(s); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/ArchiveCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/ArchiveCommand.java index 6104cb432..7726e15ee 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/ArchiveCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/ArchiveCommand.java @@ -116,9 +116,39 @@ public class ArchiveCommand extends GitCommand { * } finally { * out.close(); * } + * + * @param + * type representing an archive being created. */ public static interface Format { + /** + * Start a new archive. Entries can be included in the archive using the + * putEntry method, and then the archive should be closed using its + * close method. + * + * @param s + * underlying output stream to which to write the archive. + * @return new archive object for use in putEntry + * @throws IOException + * thrown by the underlying output stream for I/O errors + */ T createArchiveOutputStream(OutputStream s) throws IOException; + + /** + * Write an entry to an archive. + * + * @param out + * archive object from createArchiveOutputStream + * @param path + * full filename relative to the root of the archive + * @param mode + * mode (for example FileMode.REGULAR_FILE or + * FileMode.SYMLINK) + * @param loader + * blob object with data for this entry + * @throws IOException + * thrown by the underlying output stream for I/O errors + */ void putEntry(T out, String path, FileMode mode, ObjectLoader loader) throws IOException; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/GitAPIException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/GitAPIException.java index 92599ca7d..9760c49e9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/GitAPIException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/GitAPIException.java @@ -48,6 +48,11 @@ public abstract class GitAPIException extends Exception { /** * Constructs a new exception with the specified detail * message and cause. + * + * @param message + * detail message + * @param cause + * cause */ protected GitAPIException(String message, Throwable cause) { super(message, cause); @@ -56,6 +61,9 @@ public abstract class GitAPIException extends Exception { /** * Constructs a new exception with the specified detail * message and no cause. + * + * @param message + * detail message */ protected GitAPIException(String message) { super(message);