Review documentation

README.md

@@ -10,6 +10,7 @@ It is an independent open source implementation that is not affiliated with or e
 
 ## Features
 
+* Supports ACME protocol up to [draft 02](https://tools.ietf.org/html/draft-ietf-acme-acme-02)
 * Easy to use Java API
 * Requires JRE 7 or higher
 * Built with maven, packages available at [Maven Central](http://search.maven.org/#search|ga|1|g%3A%22org.shredzone.acme4j%22)

acme4j-utils/src/test/java/org/shredzone/acme4j/util/CertificateUtilsTest.java

@@ -110,8 +110,8 @@ public class CertificateUtilsTest {
     }
 
     /**
-     * Test if {@link CertificateUtils#createTlsSni02Certificate(KeyPair, String)} creates
+     * Test if {@link CertificateUtils#createTlsSni02Certificate(KeyPair, String, String)}
-     * a good certificate.
+     * creates a good certificate.
      */
     @Test
     public void testCreateTlsSni02Certificate() throws IOException, CertificateParsingException {

src/site/markdown/index.md.vm

@@ -1,11 +1,11 @@
 acme4j
 ======
 
-A Java client for the [Automatic Certificate Management Environment (ACME)](https://tools.ietf.org/html/draft-ietf-acme-acme-01) protocol.
+A Java client for the _Automatic Certificate Management Environment_ (ACME) protocol.
 
 ACME is a protocol that a certificate authority (CA) and an applicant can use to automate the process of verification and certificate issuance.
 
-This Java client helps connecting to an ACME server, and performing all necessary steps to manage certificates.
+This Java client helps connecting to an ACME server, and performing all necessary steps to manage certificates. It supports the ACME protocol up to [draft 02](https://tools.ietf.org/html/draft-ietf-acme-acme-02).
 
 It is an independent open source implementation that is not affiliated with or endorsed by _Let's Encrypt_.
 

src/site/markdown/migration.md

@@ -1,6 +1,6 @@
 # Migration Guide
 
-With version 0.6, _acme4j_ underwent a massive change to the API.
+With version 0.6, _acme4j_ underwent a major change to the API.
 
 This document will help you migrate your code to the latest API when coming from a pre-0.6 release. It should be a matter of a few minutes in most cases.
 
@@ -91,7 +91,7 @@ In previous versions, _acme4j_ used a client centric approach, with dumb data tr
 
 This approach turned out to have major disadvantages. For example, the data transport classes contained setter methods that were supposed to be used only by _acme4j_ itself. Some other setters had to be used by the library user, but only under certain circumstances. To make a long story short: The API was not self-explanatory about when to use what setters.
 
-Also, the old API was too limited to reflect coming features of the ACME specifications. `AcmeClient` would soon become a bottleneck.
+Also, the old API was too limited to reflect some features of the ACME specifications. `AcmeClient` would have become a bottleneck.
 
 As _acme4j_ is still in beta state, I prefered to make a hard cut and do a major API makeover. Trying to maintain backward compatibility by all means would end up with an overly complicated library.
 

src/site/markdown/usage/authorization.md

@@ -19,7 +19,7 @@ Collection<Challenge> combination = auth.findCombination(
         Http01Challenge.TYPE, Dns01Challenge.TYPE);
 ```
 
-The returned `combination` contains a single combination of challenges you would have to perform. If the combination consists of more than one challenge, you would have to perform _all of them_ in order to successfully authorize your domain. If `null` is returned, it means that none of your offered challenge types are acceptable to the CA.
+The returned `combination` contains a single combination of challenges you would have to perform. If the combination consists of more than one challenge, you will have to perform _all of them_ in order to successfully authorize your domain. If `null` is returned, it means that none of your offered challenge types are acceptable to the CA.
 
 If your software only implements a single challenge type, `findChallenge()` may be a little easier to use:
 
@@ -56,20 +56,17 @@ If your final certificate will contain further domains or subdomains, repeat the
 
 ## Update an Authorization
 
-For an existing Authorization object, you can always invoke `update()` to read the current server state.
+The server also provides an authorization URI. It can be retrieved from `Authorization.getLocation()`. You can recreate the `Authorization` object at a later time just by binding it to your `Session`:
-
-The server also provides an authorization URI. It can be retrieved from `Authorization.getLocation()`. You can recreate the `Authorization` object at a later time just by binding it to your `Session` and invoking `update()`:
 
 ```java
 URI authUri = ... // Authorization URI
 
 Authorization auth = Authorization.bind(session, authUri);
-auth.update();
 ```
 
-After invoking `update()`, the `Authorization` object contains the current server state about your authorization, including the domain name, the overall status, and an expiry date.
+As soon as you invoke a getter, the `Authorization` object lazily loads the current server state of your authorization, including the domain name, the overall status, and an expiry date.
 
-`update()` may throw an `AcmeRetryAfterException`, giving an estimated time in `getRetryAfter()` for when all challenges are completed. You should then wait until that moment has been reached, before trying again. The authorization state is still updated when this exception is thrown.
+You can always invoke `update()` to read the current server state again. It may throw an `AcmeRetryAfterException`, giving an estimated time in `getRetryAfter()` for when all challenges are completed. The authorization state is still updated even when this exception is thrown. If you invoke `update()` for polling the authorization state, you should wait until the moment given in the exception has been reached before trying again.
 
 ## Deactivate an Authorization
 

src/site/markdown/usage/index.md

@@ -16,7 +16,7 @@ You can also create an elliptic curve key pair:
 KeyPair keyPair = KeyPairUtils.createECKeyPair("secp256r1");
 ```
 
-> **CAUTION**: Your KeyPair is the only key to your account. If you should lose it, you will be locked out from your account and certificates. The API does currently not offer a way to regain access after a key loss. The only way is to contact the CA and ask for assistance. **It is strongly recommended to keep your key pair in a safe place!**
+> **CAUTION**: Your KeyPair is the only key to your account. If you should lose it, you will be locked out from your account and certificates. The API does currently not offer a way to recover access after a key loss. The only way is to contact the CA and ask for assistance. **It is strongly recommended to keep your key pair in a safe place!**
 
 To save a `KeyPair` (actually, the private key of the key pair) to a pem file, use this snippet:
 

src/site/markdown/usage/session.md

@@ -18,7 +18,7 @@ Session session
     = new Session("https://acme-staging.api.letsencrypt.org/directory", keyPair);
 ```
 
-However, such an URI is hard to remember and might even change in the future. Java also does not accept the certificate used by the _Let's Encrypt_ server, so calls to their servers are likely to throw a certificate exception.
+However, such an URI is hard to remember and might even change in the future. Also, Java accepts the certificate used by the _Let's Encrypt_ server since JDK 8u101, calls to their servers are likely to throw a certificate exception on older versions.
 
 For this reason, special ACME URIs should be preferred: