Adding more comments, addressing CR comments.

src/main/java/com/amazonaws/services/kinesis/clientlibrary/proxies/IKinesisProxy.java

@@ -46,12 +46,13 @@ public interface IKinesisProxy {
         throws ResourceNotFoundException, InvalidArgumentException, ExpiredIteratorException;
 
     /**
-     * Fetch information about stream. Useful for fetching the list of shards in a stream. Going forward this method is
+     * Fetch information about stream. Useful for fetching the list of shards in a stream.
-     * being deprecated. This method uses DescribeStream call, which is throttled at 10 calls per account by default.
-     * If possible try to use ListShards call available in the client, or use the getShardList to get shard info.
      * 
-     * @deprecated This method uses DescribeStream calls, which is throttled at account level. The proxy will internally
+     * @deprecated  Going forward this method is
-     * use ListShards for KinesisStreams to get the information about the shards for a given stream.
+     * being deprecated. This method uses DescribeStream call, which is throttled at 10 calls per account by default.
+     * If possible try to use ListShards call available in the client, or use the getShardList or getAllShards to get
+     * shard info. To make DescribeStream calls, use the AmazonKinesis client directly instead of using KinesisProxy.
+     * This method will be removed in the next major/minor release.
      * 
      * @param startShardId exclusive start shardId - used when paginating the list of shards.
      * @return DescribeStreamOutput object containing a description of the stream.

src/main/java/com/amazonaws/services/kinesis/clientlibrary/proxies/IKinesisProxyFactory.java

@@ -14,13 +14,11 @@
  */
 package com.amazonaws.services.kinesis.clientlibrary.proxies;
 
-import com.amazonaws.services.kinesis.AmazonKinesis;
-import com.amazonaws.services.kinesis.clientlibrary.lib.worker.KinesisClientLibConfiguration;
-
 /** 
  * Interface for a KinesisProxyFactory.
  *
- * @deprecated Deprecating since KinesisProxy is just created once, there is no use of a factory.
+ * @deprecated Deprecating since KinesisProxy is just created once, there is no use of a factory. There is no
+ * replacement for this class. This class will be removed in the next major/minor release.
  * 
  */
 @Deprecated

src/main/java/com/amazonaws/services/kinesis/clientlibrary/proxies/KinesisProxy.java

@@ -107,7 +107,8 @@ public class KinesisProxy implements IKinesisProxyExtended {
      * 
      * @deprecated Deprecating constructor, this constructor doesn't use AWS best practices, moving forward please use
      * {@link #KinesisProxy(KinesisClientLibConfiguration, AmazonKinesis)} or
-     * {@link #KinesisProxy(String, AmazonKinesis, long, int, long, int)} to create the object.
+     * {@link #KinesisProxy(String, AmazonKinesis, long, int, long, int)} to create the object. Will be removed in the
+     * next major/minor release.
      * 
      * @param streamName Data records will be fetched from this stream
      * @param credentialProvider Provides credentials for signing Kinesis requests
@@ -126,7 +127,8 @@ public class KinesisProxy implements IKinesisProxyExtended {
      * 
      * @deprecated Deprecating constructor, this constructor doesn't use AWS best practices, moving forward please use
      * {@link #KinesisProxy(KinesisClientLibConfiguration, AmazonKinesis)} or
-     * {@link #KinesisProxy(String, AmazonKinesis, long, int, long, int)} to create the object.
+     * {@link #KinesisProxy(String, AmazonKinesis, long, int, long, int)} to create the object. Will be removed in the
+     * next major/minor release.
      * 
      * @param streamName Data records will be fetched from this stream
      * @param credentialProvider Provides credentials for signing Kinesis requests
@@ -161,7 +163,8 @@ public class KinesisProxy implements IKinesisProxyExtended {
      * 
      * @deprecated Deprecating constructor, this constructor doesn't use AWS best practices, moving forward please use
      * {@link #KinesisProxy(KinesisClientLibConfiguration, AmazonKinesis)} or
-     * {@link #KinesisProxy(String, AmazonKinesis, long, int, long, int)} to create the object.
+     * {@link #KinesisProxy(String, AmazonKinesis, long, int, long, int)} to create the object. Will be removed in the
+     * next major/minor release.
      * 
      * @param streamName Data records will be fetched from this stream
      * @param credentialProvider Provides credentials for signing Kinesis requests
@@ -245,7 +248,6 @@ public class KinesisProxy implements IKinesisProxyExtended {
     @Deprecated
     public DescribeStreamResult getStreamInfo(String startShardId)
             throws ResourceNotFoundException, LimitExceededException {
-        LOG.info("Using DescribeStream calls to get shards list");
         final DescribeStreamRequest describeStreamRequest = new DescribeStreamRequest();
         // TODO: remove this once older constructors are removed
         describeStreamRequest.setRequestCredentials(credentialsProvider.getCredentials());
@@ -290,6 +292,7 @@ public class KinesisProxy implements IKinesisProxyExtended {
     }
     
     private ListShardsResult listShards(final String nextToken) {
+        // TODO: remove this before pushing code in.
         LOG.info("Using ListShards to get shards information");
         final ListShardsRequest request = new ListShardsRequest();
         // TODO: remove this once older constructors are removed

src/main/java/com/amazonaws/services/kinesis/clientlibrary/proxies/KinesisProxyFactory.java

@@ -23,7 +23,8 @@ import com.amazonaws.services.kinesis.clientlibrary.lib.worker.KinesisClientLibC
 /**
  * Factory used for instantiating KinesisProxy objects (to fetch data from Kinesis).
  * 
- * @deprecated Will be removed since proxy is created only once, we don't need a factory.
+ * @deprecated Will be removed since proxy is created only once, we don't need a factory. There is no replacement for
+ * this class. Will be removed in the next major/minor release.
  */
 @Deprecated
 public class KinesisProxyFactory implements IKinesisProxyFactory {

src/test/java/com/amazonaws/services/dynamodbv2/streamsadapter/AmazonDynamoDBStreamsAdapterClient.java

@@ -19,8 +19,8 @@ import com.amazonaws.services.kinesis.AmazonKinesis;
 import com.amazonaws.services.kinesis.AmazonKinesisClient;
 
 /**
- *
+ * This class is only used for testing purposes, to make sure that the correct calls are made while using DynamoDB
+ * streams.
  */
 public class AmazonDynamoDBStreamsAdapterClient extends AmazonKinesisClient {
-    // This class is used for testing purposes.
 }

src/test/java/com/amazonaws/services/dynamodbv2/streamsadapter/AmazonDynamoDBStreamsAdapterClientChild.java

@@ -16,8 +16,8 @@
 package com.amazonaws.services.dynamodbv2.streamsadapter;
 
 /**
- *
+ * This class is only used for testing purposes, to make sure that the correct calls are made while using DynamoDB
+ * streams.
  */
 public class AmazonDynamoDBStreamsAdapterClientChild extends AmazonDynamoDBStreamsAdapterClient {
-    // Used only for testing
 }