Corrections to the javadoc after review.

README.md

@@ -15,7 +15,8 @@ Why choose Stormpot?
 
 ... over, say, Commons-Pool? Good question! Both libraries are released under
 the Apache 2.0 license, both have thorough documentation, both have high test
-coverage (Stormpot have 100%) and both depend on nothing but Java itself.
+coverage (Stormpot has over 90% coverage) and both depend on nothing but Java
+itself.
 
 There are differences, though. Stormpot has a small invasive API, whereas
 Commons-Pool has a richer and less intrusive API. The different slants in their

src/main/java/stormpot/Allocator.java

@@ -37,7 +37,7 @@
  * in the allocator, if at all possible.
  * 
  * @author Chris Vest <[email protected]>
- *
+ * @see stormpot.Reallocator
  * @param <T> any type that implements Poolable.
  */
 public interface Allocator<T extends Poolable> {

src/main/java/stormpot/Expiration.java

@@ -32,7 +32,12 @@
  * mutable state will be thread-local. Be aware that making the
  * {@link #hasExpired(SlotInfo) hasExpired} method {@code synchronized} will
  * most likely severely reduce the performance and scalability of the pool.
- * 
+ * <p>
+ * The Expiration can be invoked several times during a
+ * {@link Pool#claim(Timeout) claim} call, so it is important that the
+ * Expiration is fast. It can easily be the dominating factor in the
+ * performance of the pool.
+ *
  * @author Chris Vest &lt;[email protected]&gt;
  */
 public interface Expiration<T extends Poolable> {
@@ -43,19 +48,20 @@ public interface Expiration<T extends Poolable> {
    * <p>
    * If the method throws an exception, then that is taken to mean that the
    * slot is invalid. The exception will bubble out of the
+   * {@link Pool#claim(Timeout) claim} method, but the mechanism is
+   * implementation specific. For this reason, it is generally advised that
+   * Expirations do not throw exceptions.
    * <p>
    * Note that this method can be called as often as several times per
    * {@link Pool#claim(Timeout) claim}. The performance of this method therefor
    * has a big influence on the percieved performance of the pool.
-   * {@link Pool#claim(Timeout) claim} method, but the mechanism is
-   * implementation specific. For this reason, it is generally advised that
-   * Expirations do not throw exceptions.
+   *
    * @param info An informative representative of the slot being tested.
    * Never <code>null</code>.
    * @return <code>true</code> if the Slot and Poolable in question should be
    * deallocated, <code>false</code> if it is valid and eligible for claiming.
    * @throws Exception If checking the validity of the Slot or Poolable somehow
-   * went wrong. In this case, the Poolable will be assumed to have expired.
+   * went wrong. In this case, the Poolable will be assumed to be expired.
    */
   boolean hasExpired(SlotInfo<? extends T> info) throws Exception;
 }

src/main/java/stormpot/Reallocator.java

@@ -27,8 +27,8 @@
  * <p>
  * The accretion of old generation garbage is inevitable, but the rate can be
  * slowed by reusing as much as possible of the Poolable instances, when they
- * to be reallocated. This interface is only here to enable this optimisation,
- * and implementing it is completely optional.
+ * are to be reallocated. This interface is only here to enable this
+ * optimisation, and implementing it is completely optional.
  *
  * @author Chris Vest &lt;[email protected]&gt;
  *
@@ -57,12 +57,13 @@ public interface Reallocator<T extends Poolable> extends Allocator<T> {
    * {@link Pool#claim(Timeout) claim} method of a pool, in the form of being
    * wrapped inside a {@link PoolException}. Pools must be able to handle these
    * exceptions in a sane manner, and are guaranteed to return to a working
-   * state if an Allocator stops throwing exceptions from its allocate method.
+   * state if a Reallocator stops throwing exceptions from its reallocate
+   * method.
    * <p>
    * Be aware that if the reallocation of an object fails with an exception,
    * then no attempts will be made to explicitly deallocate that object. This
-   * way, a failed reallocation is understood to effectively be a successful
-   * deallocation.
+   * way, a failed reallocation is implicitly understood to effectively be a
+   * successful deallocation.
    * @param slot The slot the pool wish to allocate an object for.
    * Implementors do not need to concern themselves with the details of a
    * pools slot objects. They just have to call release on them as the