aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJonathan Nieder2013-05-29 13:42:35 (EDT)
committerJonathan Nieder2013-05-29 15:36:36 (EDT)
commit659cadf06d165f1a31a0466689d77dff7330f99d (patch)
tree5eac8fd1ecd7b8b14d11b1366c7b176258879b56
parent79583aeba7819de28f1e70723713e59595e6ff18 (diff)
downloadjgit-659cadf06d165f1a31a0466689d77dff7330f99d.zip
jgit-659cadf06d165f1a31a0466689d77dff7330f99d.tar.gz
jgit-659cadf06d165f1a31a0466689d77dff7330f99d.tar.bz2
Add missing javadoc for archive coderefs/changes/54/13354/2
Document archive formats, the archive format interface, and the parameters of the GitAPIException constructors. Noticed by eclipse. Reported-by: Dani Megert <Daniel_Megert@ch.ibm.com> Change-Id: I22b5f9d4c0358bbe867c1906feec7c279e214273
-rw-r--r--org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/FormatActivator.java13
-rw-r--r--org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TarFormat.java3
-rw-r--r--org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TgzFormat.java3
-rw-r--r--org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/TxzFormat.java3
-rw-r--r--org.eclipse.jgit.archive/src/org/eclipse/jgit/archive/ZipFormat.java3
-rw-r--r--org.eclipse.jgit/src/org/eclipse/jgit/api/ArchiveCommand.java30
-rw-r--r--org.eclipse.jgit/src/org/eclipse/jgit/api/errors/GitAPIException.java8
7 files changed, 63 insertions, 0 deletions
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 f2f6140..c8ea28e 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 2e5683c..3b27489 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<ArchiveOutputStream> {
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 d68cb68..1c72bf8 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<ArchiveOutputStream> {
private final ArchiveCommand.Format<ArchiveOutputStream> 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 622571f..d1547c6 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<ArchiveOutputStream> {
private final ArchiveCommand.Format<ArchiveOutputStream> 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 1932877..a0906d4 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<ArchiveOutputStream> {
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 6104cb4..7726e15 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<OutputStream> {
* } finally {
* out.close();
* }
+ *
+ * @param <T>
+ * type representing an archive being created.
*/
public static interface Format<T extends Closeable> {
+ /**
+ * 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 92599ca..9760c49 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);