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 <Daniel_Megert@ch.ibm.com>
Change-Id: I22b5f9d4c0358bbe867c1906feec7c279e214273

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 f2f6140256193337aa182195f70238f755f1cfba..c8ea28eeff1bcfb69d2dda0c01bb6751bbebf4fd 100644 (file)
--- 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 2e5683c2b570ff15a5fa4c7de85a0fc47631aedc..3b27489e262ff83d46630270bdd053308c03cddb 100644 (file)
--- 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 d68cb68e8b993c6bf8f7b1a1984ed62404ab4319..1c72bf8dccac1c953f9b5cd0da263ead8388fe7c 100644 (file)
--- 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 622571f983271b3f2a7d98f1b3e8ed349dfb7672..d1547c683c8b4371fd5b36861b72cbb4ed9f53ab 100644 (file)
--- 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 19328775a45c4e72b2d456e1990c8078b77b7b2d..a0906d4dd52e281d357c1924fc5481a038f0229f 100644 (file)
--- 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 6104cb432da26412cdbe15eb1ad5d18523e2f263..7726e15eeb3ffe29dd56a22e68054221433895fa 100644 (file)
--- 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 92599ca7d6c914847b7fa6762c7ce5a119c35301..9760c49e961384c3d3075b43da2581fc4082ace2 100644 (file)
--- 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);