diff --git a/core/src/main/java/org/elasticsearch/index/shard/IndexShard.java b/core/src/main/java/org/elasticsearch/index/shard/IndexShard.java
index 06bb2a731c9..645b970cb66 100644
--- a/core/src/main/java/org/elasticsearch/index/shard/IndexShard.java
+++ b/core/src/main/java/org/elasticsearch/index/shard/IndexShard.java
@@ -999,7 +999,8 @@ public class IndexShard extends AbstractIndexShardComponent implements IndexSett
         this.failedEngineListener.delegates.add(failedEngineListener);
     }
 
-    /** Returns true if the indexing buffer size did change */
+    /** Change the indexing and translog buffer sizes.  If {@code IndexWriter} is currently using more than
+     *  the new buffering indexing size then we do a refresh to free up the heap. */
     public void updateBufferSize(ByteSizeValue shardIndexingBufferSize, ByteSizeValue shardTranslogBufferSize) {
 
         final EngineConfig config = engineConfig;
@@ -1046,6 +1047,8 @@ public class IndexShard extends AbstractIndexShardComponent implements IndexSett
         }
     }
 
+    /** Returns {@code true} if this shard is active (has seen indexing ops in the last {@link
+     *  IndexingMemoryController#SHARD_INACTIVE_TIME_SETTING} (default 5 minutes), else {@code false}. */
     public boolean getActive() {
         return active.get();
     }
diff --git a/core/src/main/java/org/elasticsearch/indices/memory/IndexingMemoryController.java b/core/src/main/java/org/elasticsearch/indices/memory/IndexingMemoryController.java
index 9231f9a779e..12c124297de 100644
--- a/core/src/main/java/org/elasticsearch/indices/memory/IndexingMemoryController.java
+++ b/core/src/main/java/org/elasticsearch/indices/memory/IndexingMemoryController.java
@@ -161,7 +161,6 @@ public class IndexingMemoryController extends AbstractLifecycleComponent<Indexin
 
         this.statusChecker = new ShardsIndicesStatusChecker();
 
-
         logger.debug("using indexing buffer size [{}], with {} [{}], {} [{}], {} [{}], {} [{}]",
                 this.indexingBuffer,
                 MIN_SHARD_INDEX_BUFFER_SIZE_SETTING, this.minShardIndexBufferSize,
@@ -251,7 +250,7 @@ public class IndexingMemoryController extends AbstractLifecycleComponent<Indexin
         }
     }
 
-    protected boolean isShardInactive(ShardId shardId, long inactiveTimeNS) {
+    protected boolean isShardIdle(ShardId shardId, long inactiveTimeNS) {
         final IndexShard shard = getShard(shardId);
         if (shard == null) {
             return false;
@@ -260,7 +259,7 @@ public class IndexingMemoryController extends AbstractLifecycleComponent<Indexin
     }
 
 
-    /** returns the current translog status (generation id + ops) for the given shard id. Returns null if unavailable. */
+    /** returns {@link IndexShard#getActive} if the shard exists, else null */
     protected Boolean getShardActive(ShardId shardId) {
         final IndexShard indexShard = getShard(shardId);
         if (indexShard == null) {
@@ -325,7 +324,7 @@ public class IndexingMemoryController extends AbstractLifecycleComponent<Indexin
                         logger.debug("marking shard {} as active indexing wise", shardId);
                         shardWasActive.put(shardId, true);
 
-                    } else if (isShardInactive(shardId, inactiveTime.nanos())) {
+                    } else if (isShardIdle(shardId, inactiveTime.nanos())) {
                         // Make shard inactive now
                         changes.add(ShardStatusChangeType.BECAME_INACTIVE);
                         logger.debug("marking shard {} as inactive (inactive_time[{}]) indexing wise",
diff --git a/core/src/test/java/org/elasticsearch/indices/memory/IndexingMemoryControllerTests.java b/core/src/test/java/org/elasticsearch/indices/memory/IndexingMemoryControllerTests.java
index 61c265aa9c7..4a6f29ed44e 100644
--- a/core/src/test/java/org/elasticsearch/indices/memory/IndexingMemoryControllerTests.java
+++ b/core/src/test/java/org/elasticsearch/indices/memory/IndexingMemoryControllerTests.java
@@ -109,7 +109,7 @@ public class IndexingMemoryControllerTests extends ESTestCase {
         }
 
         @Override
-        protected boolean isShardInactive(ShardId shardId, long inactiveTimeNS) {
+        protected boolean isShardIdle(ShardId shardId, long inactiveTimeNS) {
             return currentTimeInNanos() - lastIndexTimeNanos.get(shardId) >= inactiveTimeNS;
         }