Cleanup some push certificate related javadoc

Change-Id: I319ee4e99462598bf6a934b1efc7939bc4b057a5

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificate.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificate.java
index 455b46544fa6a82ec51a6719a4822a81c3f5bcda..8ee4c17bf2642349213e586677da493acca16f40 100644 (file)
--- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificate.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificate.java
@@ -49,55 +49,33 @@ package org.eclipse.jgit.transport;
  * @since 4.0
  */
 public class PushCertificate {
-
-       /** The tuple "name <email>" as presented in the push certificate */
+       /** The tuple "name &lt;email&gt;" as presented in the push certificate. */
        String pusher;
 
-       /** The remote URL the signed push goes to */
+       /** The remote URL the signed push goes to. */
        String pushee;
 
-       /** What we think about the returned signed nonce */
+       /** What we think about the returned signed nonce. */
        NonceStatus nonceStatus;
 
-       /**
-        *
-        *
-        */
+       /** Verification result of the nonce returned during push. */
        public enum NonceStatus {
-               /**
-                *
-                */
+               /** Nonce was not expected, yet client sent one anyway. */
                UNSOLICITED,
-               /**
-                *
-                */
+               /** Nonce is invalid and did not match server's expectations. */
                BAD,
-               /**
-                *
-                */
+               /** Nonce is required, but was not sent by client. */
                MISSING,
-               /**
-                *
-                */
+               /** Received nonce is valid. */
                OK,
-               /**
-                *
-                */
+               /** Received nonce is valid and within the accepted slop window. */
                SLOP
        }
 
-       /**
-        *
-        */
        String commandList;
-
-       /**
-        *
-        */
        String signature;
 
        /**
-        *
         * @return the signature, consisting of the lines received between the lines
         *         '----BEGIN GPG SIGNATURE-----\n' and the '----END GPG
         *         SIGNATURE-----\n'
@@ -115,22 +93,19 @@ public class PushCertificate {
        }
 
        /**
-        * @return the pushedCertPusher
+        * @return the tuple "name &lt;email&gt;" as presented by the client in the
+        *         push certificate.
         */
        public String getPusher() {
                return pusher;
        }
 
-       /**
-        * @return the pushedCertPushee
-        */
+       /** @return URL of the repository the push was originally sent to. */
        public String getPushee() {
                return pushee;
        }
 
-       /**
-        * @return the pushCertNonceStatus
-        */
+       /** @return verification status of the nonce embedded in the certificate. */
        public NonceStatus getNonceStatus() {
                return nonceStatus;
        }

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateParser.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateParser.java
index d111a22ca05044371197c5092e3006c68ade5f4a..d4b11a5d40ffa5637ca82e83216001c093d9ef1f 100644 (file)
--- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateParser.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateParser.java
@@ -130,18 +130,20 @@ public class PushCertificateParser extends PushCertificate {
 
        /**
         * Receive a list of commands from the input encapsulated in a push
-        * certificate. This method doesn't deal with the first line "push-cert \NUL
-        * <capabilities>", but assumes the first line including the capabilities
-        * has already been dealt with.
+        * certificate. This method doesn't parse the first line "push-cert \NUL
+        * &lt;capabilities&gt;", but assumes the first line including the
+        * capabilities has already been handled by the caller.
         *
         * @param pckIn
         *            where we take the push certificate header from.
         * @param stateless
-        *            If this server is run as a stateless server, such that it
-        *            cannot store the sent push certificate and needs to validate
-        *            what the client sends back.
-        *
+        *            affects nonce verification. When {@code stateless = true} the
+        *            {@code NonceGenerator} will allow for some time skew caused by
+        *            clients disconnected and reconnecting in the stateless smart
+        *            HTTP protocol.
         * @throws IOException
+        *             if the certificate from the client is badly malformed or the
+        *             client disconnects before sending the entire certificate.
         */
        public void receiveHeader(PacketLineIn pckIn, boolean stateless)
                        throws IOException {