Update the Documentation for a Variety of Components

pom.xml

@@ -242,6 +242,35 @@
           </execution>
         </executions>
       </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <version>2.10.3</version>
+        <configuration>
+          <excludePackageNames>com.amazonaws.services.kinesis.producer.protobuf</excludePackageNames>
+        </configuration>
+        <executions>
+          <execution>
+            <id>attach-javadocs</id>
+            <goals>
+              <goal>jar</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-source-plugin</artifactId>
+        <version>3.0.1</version>
+        <executions>
+          <execution>
+            <id>attach-sources</id>
+            <goals>
+              <goal>jar</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
     </plugins>
 
   </build>

src/main/java/com/amazonaws/services/kinesis/clientlibrary/interfaces/v2/IRecordProcessor.java

@@ -45,10 +45,16 @@ public interface IRecordProcessor {
 
     /**
      * Invoked by the Amazon Kinesis Client Library to indicate it will no longer send data records to this
-     * RecordProcessor instance. 
+     * RecordProcessor instance.
      *
-     * @param shutdownInput Provides information and capabilities (eg checkpointing) related to shutdown of this record
-     *        processor.
+     * <h2><b>Warning</b></h2>
+     *
+     * When the value of {@link ShutdownInput#getShutdownReason()} is
+     * {@link com.amazonaws.services.kinesis.clientlibrary.lib.worker.ShutdownReason#TERMINATE} it is required that you
+     * checkpoint. Failure to do so will result in an IllegalArgumentException, and the KCL no longer making progress.
+     *
+     * @param shutdownInput
+     *            Provides information and capabilities (eg checkpointing) related to shutdown of this record processor.
      */
     void shutdown(ShutdownInput shutdownInput);
 

src/main/java/com/amazonaws/services/kinesis/clientlibrary/lib/worker/KinesisClientLibConfiguration.java

@@ -52,7 +52,8 @@ public class KinesisClientLibConfiguration {
     public static final int DEFAULT_MAX_RECORDS = 10000;
 
     /**
-     * Idle time between record reads in milliseconds.
+     * The default value for how long the {@link ShardConsumer} should sleep if no records are returned from the call to
+     * {@link com.amazonaws.services.kinesis.AmazonKinesis#getRecords(com.amazonaws.services.kinesis.model.GetRecordsRequest)}.
      */
     public static final long DEFAULT_IDLETIME_BETWEEN_READS_MILLIS = 1000L;
 
@@ -790,7 +791,23 @@ public KinesisClientLibConfiguration withMaxRecords(int maxRecords) {
     }
 
     /**
-     * @param idleTimeBetweenReadsInMillis Idle time between calls to fetch data from Kinesis
+     * Controls how long the KCL will sleep if no records are returned from Kinesis
+     *
+     * <p>
+     * This value is only used when no records are returned; if records are returned, the {@link com.amazonaws.services.kinesis.clientlibrary.lib.worker.ProcessTask} will
+     * immediately retrieve the next set of records after the call to
+     * {@link com.amazonaws.services.kinesis.clientlibrary.interfaces.v2.IRecordProcessor#processRecords(ProcessRecordsInput)}
+     * has returned. Setting this value to high may result in the KCL being unable to catch up. If you are changing this
+     * value it's recommended that you enable {@link #withCallProcessRecordsEvenForEmptyRecordList(boolean)}, and
+     * monitor how far behind the records retrieved are by inspecting
+     * {@link com.amazonaws.services.kinesis.clientlibrary.types.ProcessRecordsInput#getMillisBehindLatest()}, and the
+     * <a href=
+     * "http://docs.aws.amazon.com/streams/latest/dev/monitoring-with-cloudwatch.html#kinesis-metrics-stream">CloudWatch
+     * Metric: GetRecords.MillisBehindLatest</a>
+     * </p>
+     *
+     * @param idleTimeBetweenReadsInMillis
+     *            how long to sleep between GetRecords calls when no records are returned.
      * @return KinesisClientLibConfiguration
      */
     public KinesisClientLibConfiguration withIdleTimeBetweenReadsInMillis(long idleTimeBetweenReadsInMillis) {