Cleanup comments in SequenceNumbersService.java

This commit cleans up the comments in SequenceNumbersService, making
them uniform in their formatting and taking advantage of the line-length
limit of 140 characters.

core/src/main/java/org/elasticsearch/index/seqno/SequenceNumbersService.java

@@ -16,6 +16,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+
 package org.elasticsearch.index.seqno;
 
 import org.elasticsearch.index.IndexSettings;
@@ -25,10 +26,13 @@ import org.elasticsearch.index.shard.ShardId;
 import java.util.Set;
 
 /**
- * a very light weight implementation. will be replaced with proper machinery later
+ * Encapsulates the local and global checkpoints into a single service for use as a shard component.
  */
 public class SequenceNumbersService extends AbstractIndexShardComponent {
 
+    /**
+     * Represents an unassigned sequence number (e.g., can be used on primary operations before they are executed).
+     */
     public static final long UNASSIGNED_SEQ_NO = -2L;
 
     /**
@@ -36,8 +40,8 @@ public class SequenceNumbersService extends AbstractIndexShardComponent {
      */
     public static final long NO_OPS_PERFORMED = -1L;
 
-    final LocalCheckpointService localCheckpointService;
+    private final LocalCheckpointService localCheckpointService;
-    final GlobalCheckpointService globalCheckpointService;
+    private final GlobalCheckpointService globalCheckpointService;
 
     /**
      * Initialize the sequence number service. The {@code maxSeqNo} should be set to the last sequence number assigned by this shard, or
@@ -63,58 +67,77 @@ public class SequenceNumbersService extends AbstractIndexShardComponent {
     }
 
     /**
-     * generates a new sequence number.
+     * Issue the next sequence number. Note that you must call {@link #markSeqNoAsCompleted(long)} after the operation for which the
-     * Note: you must call {@link #markSeqNoAsCompleted(long)} after the operation for which this seq# was generated
+     * issued sequence number completes (whether or not the operation completes successfully).
-     * was completed (whether successfully or with a failure)
+     *
+     * @return the next assigned sequence number
      */
     public long generateSeqNo() {
         return localCheckpointService.generateSeqNo();
     }
 
     /**
-     * Gets the maximum sequence number seen so far.  See {@link LocalCheckpointService#getMaxSeqNo()} for details.
+     * The maximum sequence number issued so far. See {@link LocalCheckpointService#getMaxSeqNo()} for additional details.
+     *
+     * @return the maximum sequence number
      */
     public long getMaxSeqNo() {
         return localCheckpointService.getMaxSeqNo();
     }
 
     /**
-     * marks the given seqNo as completed. See {@link LocalCheckpointService#markSeqNoAsCompleted(long)}
+     * Marks the processing of the provided sequence number as completed as updates the checkpoint if possible.
-     * more details
+     * See {@link LocalCheckpointService#markSeqNoAsCompleted(long)} for additional details.
+     *
+     * @param seqNo the sequence number to mark as completed
      */
-    public void markSeqNoAsCompleted(long seqNo) {
+    public void markSeqNoAsCompleted(final long seqNo) {
         localCheckpointService.markSeqNoAsCompleted(seqNo);
     }
 
     /**
-     * Gets sequence number related stats
+     * The current sequence number stats.
+     *
+     * @return stats encapuslating the maximum sequence number, the local checkpoint and the global checkpoint
      */
     public SeqNoStats stats() {
         return new SeqNoStats(getMaxSeqNo(), getLocalCheckpoint(), getGlobalCheckpoint());
     }
 
     /**
-     * notifies the service of a local checkpoint.
+     * Notifies the service to update the local checkpoint for the shard with the provided allocation ID.
-     * see {@link GlobalCheckpointService#updateLocalCheckpoint(String, long)} for details.
+     *
+     * @param allocationId the allocation ID of the shard to update the local checkpoint for
+     * @param checkpoint   the local checkpoint for the shard
      */
-    public void updateLocalCheckpointForShard(String allocationId, long checkpoint) {
+    public void updateLocalCheckpointForShard(final String allocationId, final long checkpoint) {
         globalCheckpointService.updateLocalCheckpoint(allocationId, checkpoint);
     }
 
     /**
-     * marks the allocationId as "in sync" with the primary shard.
+     * Marks the shard with the provided allocation ID as in-sync with the primary shard. See
-     * see {@link GlobalCheckpointService#markAllocationIdAsInSync(String)} for details.
+     * {@link GlobalCheckpointService#markAllocationIdAsInSync(String)} for additional details.
      *
-     * @param allocationId    allocationId of the recovering shard
+     * @param allocationId the allocation ID of the shard to mark as in-sync
      */
-    public void markAllocationIdAsInSync(String allocationId) {
+    public void markAllocationIdAsInSync(final String allocationId) {
         globalCheckpointService.markAllocationIdAsInSync(allocationId);
     }
 
+    /**
+     * Returns the local checkpoint for the shard.
+     *
+     * @return the local checkpoint
+     */
     public long getLocalCheckpoint() {
         return localCheckpointService.getCheckpoint();
     }
 
+    /**
+     * Returns the global checkpoint for the shard.
+     *
+     * @return the global checkpoint
+     */
     public long getGlobalCheckpoint() {
         return globalCheckpointService.getCheckpoint();
     }
@@ -122,28 +145,30 @@ public class SequenceNumbersService extends AbstractIndexShardComponent {
     /**
      * Scans through the currently known local checkpoint and updates the global checkpoint accordingly.
      *
-     * @return true if the checkpoint has been updated or if it can not be updated since one of the local checkpoints
+     * @return {@code true} if the checkpoint has been updated or if it can not be updated since one of the local checkpoints of one of the
-     * of one of the active allocations is not known.
+     * active allocations is not known.
      */
     public boolean updateGlobalCheckpointOnPrimary() {
         return globalCheckpointService.updateCheckpointOnPrimary();
     }
 
     /**
-     * updates the global checkpoint on a replica shard (after it has been updated by the primary).
+     * Updates the global checkpoint on a replica shard after it has been updated by the primary.
+     *
+     * @param checkpoint the global checkpoint
      */
-    public void updateGlobalCheckpointOnReplica(long checkpoint) {
+    public void updateGlobalCheckpointOnReplica(final long checkpoint) {
         globalCheckpointService.updateCheckpointOnReplica(checkpoint);
     }
 
     /**
-     * Notifies the service of the current allocation ids in the cluster state.
+     * Notifies the service of the current allocation IDs in the cluster state. See
-     * see {@link GlobalCheckpointService#updateAllocationIdsFromMaster(Set, Set)} for details.
+     * {@link GlobalCheckpointService#updateAllocationIdsFromMaster(Set, Set)} for details.
      *
      * @param activeAllocationIds       the allocation ids of the currently active shard copies
      * @param initializingAllocationIds the allocation ids of the currently initializing shard copies
      */
-    public void updateAllocationIdsFromMaster(Set<String> activeAllocationIds, Set<String> initializingAllocationIds) {
+    public void updateAllocationIdsFromMaster(final Set<String> activeAllocationIds, final Set<String> initializingAllocationIds) {
         globalCheckpointService.updateAllocationIdsFromMaster(activeAllocationIds, initializingAllocationIds);
     }