Merge pull request #701 from mattrjacobs/javadoc

Fix Javadoc warnings

hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java

@@ -278,7 +278,7 @@ protected AbstractCommand(HystrixCommandGroupKey group, HystrixCommandKey key, H
     /**
      * Allow the Collapser to mark this command instance as being used for a collapsed request and how many requests were collapsed.
      * 
-     * @param sizeOfBatch
+     * @param sizeOfBatch number of commands in request batch
      */
     /* package */void markAsCollapsedCommand(int sizeOfBatch) {
         getMetrics().markCollapsed(sizeOfBatch);
@@ -955,8 +955,6 @@ private static void setRequestContextIfNeeded(final HystrixRequestContext curren
     /**
      * Get the TryableSemaphore this HystrixCommand should use if a fallback occurs.
      * 
-     * @param circuitBreaker
-     * @param fallbackSemaphore
      * @return TryableSemaphore
      */
     protected TryableSemaphore getFallbackSemaphore() {
@@ -978,8 +976,6 @@ protected TryableSemaphore getFallbackSemaphore() {
     /**
      * Get the TryableSemaphore this HystrixCommand should use for execution if not running in a separate thread.
      * 
-     * @param circuitBreaker
-     * @param fallbackSemaphore
      * @return TryableSemaphore
      */
     protected TryableSemaphore getExecutionSemaphore() {
@@ -1469,7 +1465,7 @@ private R wrapWithOnEmitHook(R r) {
      * <p>
      * This will only throw an HystrixRuntimeException, HystrixBadRequestException or IllegalStateException
      * 
-     * @param e
+     * @param e initial exception
      * @return HystrixRuntimeException, HystrixBadRequestException or IllegalStateException
      */
     protected RuntimeException decomposeException(Exception e) {
@@ -1661,8 +1657,8 @@ private ExecutionResult(List<HystrixEventType> events, int executionTime, Except
         /**
          * Creates a new ExecutionResult by adding the defined 'events' to the ones on the current instance.
          * 
-         * @param events
-         * @return
+         * @param events events to add
+         * @return new {@link com.netflix.hystrix.AbstractCommand.ExecutionResult} with events added
          */
         public ExecutionResult addEvents(HystrixEventType... events) {
             return new ExecutionResult(getUpdatedList(this.events, events), executionTime, exception, numEmissions, numFallbackEmissions);

hystrix-core/src/main/java/com/netflix/hystrix/HystrixCollapser.java

@@ -519,7 +519,7 @@ public interface CollapsedRequest<ResponseType, RequestArgumentType> {
         /**
          * When set any client thread blocking on get() will immediately be unblocked and receive the exception.
          * 
-         * @param exception
+         * @param exception exception to set on response
          * @throws IllegalStateException
          *             if called more than once or after setResponse.
          */

hystrix-core/src/main/java/com/netflix/hystrix/HystrixCollapserKey.java

@@ -42,7 +42,7 @@ private Factory() {
         /**
          * Retrieve (or create) an interned HystrixCollapserKey instance for a given name.
          * 
-         * @param name
+         * @param name collapser name
          * @return HystrixCollapserKey instance that is interned (cached) so a given name will always retrieve the same instance.
          */
         public static HystrixCollapserKey asKey(String name) {

hystrix-core/src/main/java/com/netflix/hystrix/HystrixCollapserProperties.java

@@ -325,7 +325,7 @@ public Setter withMetricsRollingPercentileWindowBuckets(int value) {
          * Return a static representation of the properties with values from the Builder so that UnitTests can create properties that are not affected by the actual implementations which pick up their
          * values dynamically.
          * 
-         * @param builder
+         * @param builder collapser properties builder
          * @return HystrixCollapserProperties
          */
         /* package */static HystrixCollapserProperties asMock(final Setter builder) {

hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommandGroupKey.java

@@ -44,7 +44,7 @@ private Factory() {
         /**
          * Retrieve (or create) an interned HystrixCommandGroup instance for a given name.
          * 
-         * @param name
+         * @param name command group name
          * @return HystrixCommandGroup instance that is interned (cached) so a given name will always retrieve the same instance.
          */
         public static HystrixCommandGroupKey asKey(String name) {

hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommandKey.java

@@ -42,7 +42,7 @@ private Factory() {
         /**
          * Retrieve (or create) an interned HystrixCommandKey instance for a given name.
          * 
-         * @param name
+         * @param name command name
          * @return HystrixCommandKey instance that is interned (cached) so a given name will always retrieve the same instance.
          */
         public static HystrixCommandKey asKey(String name) {

hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommandMetrics.java

@@ -226,7 +226,7 @@ public int getCurrentConcurrentExecutionCount() {
     /**
      * When a {@link HystrixCommand} successfully completes it will call this method to report its success along with how long the execution took.
      * 
-     * @param duration
+     * @param duration command duration
      */
     /* package */void markSuccess(long duration) {
         eventNotifier.markEvent(HystrixEventType.SUCCESS, key);
@@ -236,7 +236,7 @@ public int getCurrentConcurrentExecutionCount() {
     /**
      * When a {@link HystrixCommand} fails to complete it will call this method to report its failure along with how long the execution took.
      * 
-     * @param duration
+     * @param duration command duration
      */
     /* package */void markFailure(long duration) {
         eventNotifier.markEvent(HystrixEventType.FAILURE, key);
@@ -247,7 +247,7 @@ public int getCurrentConcurrentExecutionCount() {
      * When a {@link HystrixCommand} times out (fails to complete) it will call this method to report its failure along with how long the command waited (this time should equal or be very close to the
      * timeout value).
      * 
-     * @param duration
+     * @param duration command duration
      */
     /* package */void markTimeout(long duration) {
         eventNotifier.markEvent(HystrixEventType.TIMEOUT, key);
@@ -341,7 +341,7 @@ public long getRollingMaxConcurrentExecutions() {
     /**
      * When a command is fronted by an {@link HystrixCollapser} then this marks how many requests are collapsed into the single command execution.
      * 
-     * @param numRequestsCollapsedToBatch
+     * @param numRequestsCollapsedToBatch number of requests which got batched
      */
     /* package */void markCollapsed(int numRequestsCollapsedToBatch) {
         eventNotifier.markEvent(HystrixEventType.COLLAPSED, key);

hystrix-core/src/main/java/com/netflix/hystrix/HystrixObservableCollapser.java

@@ -503,7 +503,7 @@ public static Setter withCollapserKey(HystrixCollapserKey collapserKey) {
         /**
          * {@link Scope} defining what scope the collapsing should occur within
          * 
-         * @param scope
+         * @param scope collapser scope
          * 
          * @return Setter for fluent interface via method chaining
          */

hystrix-core/src/main/java/com/netflix/hystrix/HystrixThreadPoolKey.java

@@ -44,7 +44,7 @@ private Factory() {
         /**
          * Retrieve (or create) an interned HystrixThreadPoolKey instance for a given name.
          * 
-         * @param name
+         * @param name thread pool name
          * @return HystrixThreadPoolKey instance that is interned (cached) so a given name will always retrieve the same instance.
          */
         public static HystrixThreadPoolKey asKey(String name) {

hystrix-core/src/main/java/com/netflix/hystrix/HystrixThreadPoolProperties.java

@@ -249,7 +249,7 @@ public Setter withMetricsRollingStatisticalWindowBuckets(int value) {
          * Return a static representation of the properties with values from the Builder so that UnitTests can create properties that are not affected by the actual implementations which pick up their
          * values dynamically.
          * 
-         * @param builder
+         * @param builder builder for a {@link HystrixThreadPoolProperties}
          * @return HystrixThreadPoolProperties
          */
         /* package */static HystrixThreadPoolProperties asMock(final Setter builder) {

hystrix-core/src/main/java/com/netflix/hystrix/collapser/CollapsedRequestObservableFunction.java

@@ -59,7 +59,7 @@ public R getArgument() {
      * 
      * @throws IllegalStateException
      *             if called more than once or after setException.
-     * @param response
+     * @param response response to give to initial command
      */
     @Override
     public void setResponse(T response) {
@@ -89,7 +89,7 @@ public void setResponse(T response) {
     /**
      * Set an exception if a response is not yet received otherwise skip it
      * 
-     * @param e
+     * @param e synthetic error to set on initial command when no actual response is available
      */
     public void setExceptionIfResponseNotReceived(Exception e) {
         while (true) {
@@ -139,7 +139,7 @@ public Exception setExceptionIfResponseNotReceived(Exception e, String exception
      * 
      * @throws IllegalStateException
      *             if called more than once or after setResponse.
-     * @param response
+     * @param e received exception that gets set on the initial command
      */
     @Override
     public void setException(Exception e) {

hystrix-core/src/main/java/com/netflix/hystrix/collapser/RequestBatch.java

@@ -103,7 +103,6 @@ public Observable<ResponseType> offer(RequestArgumentType arg) {
      * think a response was never received and will either block indefinitely or will timeout while waiting.</li>
      * </ul>
      * 
-     * @param args
      */
     public void executeBatchIfNotAlreadyStarted() {
         /*

hystrix-core/src/main/java/com/netflix/hystrix/collapser/RequestCollapser.java

@@ -53,11 +53,10 @@ public class RequestCollapser<BatchReturnType, ResponseType, RequestArgumentType
     private final HystrixConcurrencyStrategy concurrencyStrategy;
 
     /**
-     * @param maxRequestsInBatch
-     *            Maximum number of requests to include in a batch. If request count hits this threshold it will result in batch executions earlier than the scheduled delay interval.
-     * @param timerDelayInMilliseconds
-     *            Interval between batch executions.
-     * @param commandCollapser
+     * @param commandCollapser collapser which will create the batched requests and demultiplex the results
+     * @param properties collapser properties that define how collapsing occurs
+     * @param timer {@link CollapserTimer} which performs the collapsing
+     * @param concurrencyStrategy strategy for managing the {@link Callable}s generated by {@link RequestCollapser}
      */
     RequestCollapser(HystrixCollapserBridge<BatchReturnType, ResponseType, RequestArgumentType> commandCollapser, HystrixCollapserProperties properties, CollapserTimer timer, HystrixConcurrencyStrategy concurrencyStrategy) {
         this.commandCollapser = commandCollapser; // the command with implementation of abstract methods we need 
@@ -70,7 +69,7 @@ public class RequestCollapser<BatchReturnType, ResponseType, RequestArgumentType
     /**
      * Submit a request to a batch. If the batch maxSize is hit trigger the batch immediately.
      * 
-     * @param arg
+     * @param arg argument to a {@link RequestCollapser}
      * @return Observable<ResponseType>
      * @throws IllegalStateException
      *             if submitting after shutdown

hystrix-core/src/main/java/com/netflix/hystrix/collapser/RequestCollapserFactory.java

@@ -136,7 +136,7 @@ private RequestCollapser<BatchReturnType, ResponseType, RequestArgumentType> get
     /**
      * Lookup (or create and store) the RequestVariable for a given HystrixCollapserKey.
      * 
-     * @param key
+     * @param commandCollapser collapser to retrieve {@link HystrixRequestVariableHolder} for
      * @return HystrixRequestVariableHolder
      */
     @SuppressWarnings("unchecked")
@@ -259,7 +259,7 @@ public static Setter withCollapserKey(HystrixCollapserKey collapserKey) {
         /**
          * {@link Scope} defining what scope the collapsing should occur within
          * 
-         * @param scope
+         * @param scope collapser scope
          * 
          * @return Setter for fluent interface via method chaining
          */

hystrix-core/src/main/java/com/netflix/hystrix/strategy/eventnotifier/HystrixEventNotifier.java

@@ -42,8 +42,8 @@ public abstract class HystrixEventNotifier {
      * <p>
      * <b>Default Implementation: </b> Does nothing
      * 
-     * @param eventType
-     * @param key
+     * @param eventType event type
+     * @param key event key
      */
     public void markEvent(HystrixEventType eventType, HystrixCommandKey key) {
         // do nothing

hystrix-core/src/main/java/com/netflix/hystrix/strategy/properties/HystrixPropertiesChainedArchaiusProperty.java

@@ -70,7 +70,7 @@ public ChainLink() {
         }
 
         /**
-         * @param nextProperty
+         * @param nextProperty next property in the chain
          */
         public ChainLink(ChainLink<T> nextProperty) {
             next = nextProperty;
@@ -110,7 +110,7 @@ public T get() {
         }
 
         /**
-         * @param r
+         * @param r callback to execut
          */
         public void addCallback(Runnable r) {
             callbacks.add(r);

hystrix-core/src/main/java/com/netflix/hystrix/strategy/properties/HystrixPropertiesStrategy.java

@@ -64,8 +64,8 @@ public HystrixCommandProperties getCommandProperties(HystrixCommandKey commandKe
      * <p>
      * Returns {@link HystrixCommandKey#name()}
      * 
-     * @param commandKey
-     * @param builder
+     * @param commandKey command key used in determining command's cache key
+     * @param builder builder for {@link HystrixCommandProperties} used in determining command's cache key
      * @return String value to be used as the cache key of a {@link HystrixCommandProperties} implementation.
      */
     public String getCommandPropertiesCacheKey(HystrixCommandKey commandKey, HystrixCommandProperties.Setter builder) {
@@ -102,9 +102,9 @@ public HystrixThreadPoolProperties getThreadPoolProperties(HystrixThreadPoolKey
      * <b>Default Implementation</b>
      * <p>
      * Returns {@link HystrixThreadPoolKey#name()}
-     * 
-     * @param threadPoolKey
-     * @param builder
+     *
+     * @param threadPoolKey thread pool key used in determining thread pool's cache key
+     * @param builder builder for {@link HystrixThreadPoolProperties} used in determining thread pool's cache key
      * @return String value to be used as the cache key of a {@link HystrixThreadPoolProperties} implementation.
      */
     public String getThreadPoolPropertiesCacheKey(HystrixThreadPoolKey threadPoolKey, HystrixThreadPoolProperties.Setter builder) {
@@ -141,9 +141,9 @@ public HystrixCollapserProperties getCollapserProperties(HystrixCollapserKey col
      * <b>Default Implementation</b>
      * <p>
      * Returns {@link HystrixCollapserKey#name()}
-     * 
-     * @param collapserKey
-     * @param builder
+     *
+     * @param collapserKey collapser key used in determining collapser's cache key
+     * @param builder builder for {@link HystrixCollapserProperties} used in determining collapser's cache key
      * @return String value to be used as the cache key of a {@link HystrixCollapserProperties} implementation.
      */
     public String getCollapserPropertiesCacheKey(HystrixCollapserKey collapserKey, HystrixCollapserProperties.Setter builder) {

hystrix-core/src/main/java/com/netflix/hystrix/strategy/properties/HystrixProperty.java

@@ -130,7 +130,7 @@ public T get() {
         /**
          * When retrieved this will iterate over the contained {@link HystrixProperty} instances until a non-null value is found and return that.
          * 
-         * @param values
+         * @param values properties to iterate over
          * @return first non-null value or null if none found
          */
         @SafeVarargs

hystrix-core/src/main/java/com/netflix/hystrix/util/HystrixRollingNumber.java

@@ -114,8 +114,8 @@ public void add(HystrixRollingNumberEvent type, long value) {
      * <p>
      * The {@link HystrixRollingNumberEvent} must be a "max updater" type <code>HystrixRollingNumberEvent.isMaxUpdater() == true</code>.
      * 
-     * @param type
-     * @param value
+     * @param type  HystrixRollingNumberEvent defining which counter to retrieve values from
+     * @param value long value to be given to the max updater
      */
     public void updateRollingMax(HystrixRollingNumberEvent type, long value) {
         getCurrentBucket().getMaxUpdater(type).update(value);
@@ -144,7 +144,7 @@ public void reset() {
      * <p>
      * The {@link HystrixRollingNumberEvent} must be a "counter" type <code>HystrixRollingNumberEvent.isCounter() == true</code>.
      * 
-     * @param type
+     * @param type HystrixRollingNumberEvent defining which counter to retrieve values from
      * @return cumulative sum of all increments and adds for the given {@link HystrixRollingNumberEvent} counter type
      */
     public long getCumulativeSum(HystrixRollingNumberEvent type) {

hystrix-core/src/main/java/com/netflix/hystrix/util/HystrixRollingPercentile.java

@@ -379,8 +379,8 @@ public int getPercentile(double percentile) {
          * @see <a href="http://en.wikipedia.org/wiki/Percentile">Percentile (Wikipedia)</a>
          * @see <a href="http://cnx.org/content/m10805/latest/">Percentile</a>
          * 
-         * @param percent
-         * @return
+         * @param percent percentile of data desired
+         * @return data at the asked-for percentile.  Interpolation is used if exactness is not possible
          */
         private int computePercentile(double percent) {
             // Some just-in-case edge cases

hystrix-core/src/test/java/com/netflix/hystrix/HystrixCollapserTest.java

@@ -1224,7 +1224,7 @@ public void clear() {
          * <p>
          * This is because executing multiple times in a tight-loop would not achieve the correct behavior, such as batching, since it will all execute "now" not after intervals of time.
          * 
-         * @param timeInMilliseconds
+         * @param timeInMilliseconds amount of time to increment
          */
         public synchronized void incrementTime(int timeInMilliseconds) {
             for (ATask t : tasks) {

hystrix-core/src/test/java/com/netflix/hystrix/HystrixCommandPropertiesTest.java

@@ -59,7 +59,7 @@ public class HystrixCommandPropertiesTest {
      * Return a static representation of the properties with values from the Builder so that UnitTests can create properties that are not affected by the actual implementations which pick up their
      * values dynamically.
      * 
-     * @param builder
+     * @param builder command properties builder
      * @return HystrixCommandProperties
      */
     /* package */static HystrixCommandProperties asMock(final Setter builder) {