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 455b46544..8ee4c17bf 100644
--- 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 @@
  * @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 String getCommandList() {
 	}
 
 	/**
-	 * @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 d111a22ca..d4b11a5d4 100644
--- 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 @@ private String parseNextLine(PacketLineIn pckIn, String startingWith)
 
 	/**
 	 * 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 {