Fix Javadoc generation and some Javadoc warnings

Netflix · Mar 6, 2015 · 17b2cdf · 17b2cdf
1 parent 1377edd
commit 17b2cdf
Show file tree

Hide file tree

Showing 6 changed files with 32 additions and 38 deletions.
diff --git a/hystrix-core/build.gradle b/hystrix-core/build.gradle
@@ -13,18 +13,15 @@ javadoc {
     // we do not want the com.netflix.hystrix.util package include
     exclude '**/util/**'
 
-    options {
-        doclet = "org.benjchristensen.doclet.DocletExclude"
+        options {
+	doclet = "org.benjchristensen.doclet.DocletExclude"
         docletpath = [rootProject.file('./gradle/doclet-exclude.jar')]
         stylesheetFile = rootProject.file('./gradle/javadocStyleSheet.css')
         windowTitle = "Hystrix Javadoc ${project.version}"
     }
     options.addStringOption('top').value = '<a href="https://github.com/Netflix/Hystrix"><img width="92" height="79" border="0" align="left" src="http://netflix.github.com/Hystrix/images/hystrix-logo-small.png"></a><h2 class="title" style="padding-top:40px">Hystrix: Latency and Fault Tolerance for Distributed Systems</h2>'
 }
 
-// skip if not on Java 6 (every JDK changes Javadoc behavior)
-javadoc.onlyIf { JavaVersion.current().java6 }
-
 jar {
     manifest {
         name = 'hystrix-core'

diff --git a/hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java b/hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java
@@ -288,7 +288,7 @@ protected AbstractCommand(HystrixCommandGroupKey group, HystrixCommandKey key, H
     /**
      * Used for asynchronous execution of command with a callback by subscribing to the {@link Observable}.
      * <p>
-     * This eagerly starts execution of the command the same as {@link #queue()} and {@link #execute()}.
+     * This eagerly starts execution of the command the same as {@link HystrixCommand#queue()} and {@link HystrixCommand#execute()}.
      * <p>
      * A lazy {@link Observable} can be obtained from {@link #toObservable()}.
      * <p>
@@ -1108,7 +1108,7 @@ public AbstractCommand<R> getCommand() {
     }
 
     /**
-     * @return {@link HystrixCommandGroupKey} used to group together multiple {@link HystrixFutureCommand} objects.
+     * @return {@link HystrixCommandGroupKey} used to group together multiple {@link AbstractCommand} objects.
      *         <p>
      *         The {@link HystrixCommandGroupKey} is used to represent a common relationship between commands. For example, a library or team name, the system all related commands interace with,
      *         common business purpose etc.
@@ -1137,16 +1137,16 @@ public HystrixThreadPoolKey getThreadPoolKey() {
     }
 
     /**
-     * The {@link HystrixCommandMetrics} associated with this {@link HystrixFutureCommand} instance.
-     * 
+     * The {@link HystrixCommandMetrics} associated with this {@link AbstractCommand} instance.
+     *
      * @return HystrixCommandMetrics
      */
     public HystrixCommandMetrics getMetrics() {
         return metrics;
     }
 
     /**
-     * The {@link HystrixCommandProperties} associated with this {@link HystrixFutureCommand} instance.
+     * The {@link HystrixCommandProperties} associated with this {@link AbstractCommand} instance.
      * 
      * @return HystrixCommandProperties
      */
@@ -1683,7 +1683,7 @@ public Exception getException() {
         }
 
         /**
-         * This method may be called many times for {@code HystrixEventType.EMIT} and {@link HystrixEventType.FALLBACK_EMIT}.
+         * This method may be called many times for {@code HystrixEventType.EMIT} and {@code HystrixEventType.FALLBACK_EMIT}.
          * To save on storage, on the first time we see that event type, it gets added to the event list, and the count gets incremented.
          * @param eventType emission event
          * @return "updated" {@link ExecutionResult}

diff --git a/hystrix-core/src/main/java/com/netflix/hystrix/HystrixExecutable.java b/hystrix-core/src/main/java/com/netflix/hystrix/HystrixExecutable.java
@@ -69,14 +69,13 @@ public interface HystrixExecutable<R> extends HystrixInvokable<R> {
      * <b>Callback Scheduling</b>
      * <p>
      * <ul>
-     * <li>When using {@link ExecutionIsolationStrategy#THREAD} this defaults to using {@link Schedulers#threadPoolForComputation()} for callbacks.</li>
+     * <li>When using {@link ExecutionIsolationStrategy#THREAD} this defaults to using {@link Schedulers#computation()} for callbacks.</li>
      * <li>When using {@link ExecutionIsolationStrategy#SEMAPHORE} this defaults to using {@link Schedulers#immediate()} for callbacks.</li>
      * </ul>
-     * Use {@link HystrixCommand#toObservable(rx.Scheduler)} or {@link HystrixCollapser#toObservable(rx.Scheduler)} to schedule the callback differently.
      * <p>
      * See https://github.com/Netflix/RxJava/wiki for more information.
-     * 
-     * @return {@code Observable<R>} that executes and calls back with the result of {@link #run()} execution or a fallback from {@link #getFallback()} if the command fails for any reason.
+     *
+     * @return {@code Observable<R>} that executes and calls back with the result of the command execution or a fallback if the command fails for any reason.
      * @throws HystrixRuntimeException
      *             if a fallback does not exist
      *             <p>

diff --git a/hystrix-core/src/main/java/com/netflix/hystrix/HystrixObservable.java b/hystrix-core/src/main/java/com/netflix/hystrix/HystrixObservable.java
@@ -32,21 +32,20 @@ public interface HystrixObservable<R> extends HystrixInvokable<R> {
     /**
      * Used for asynchronous execution of command with a callback by subscribing to the {@link Observable}.
      * <p>
-     * This eagerly starts execution of the command the same as {@link #queue()} and {@link #execute()}.
+     * This eagerly starts execution of the command the same as {@link HystrixCommand#queue()} and {@link HystrixCommand#execute()}.
      * <p>
      * A lazy {@link Observable} can be obtained from {@link #toObservable()}.
      * <p>
      * <b>Callback Scheduling</b>
      * <p>
      * <ul>
-     * <li>When using {@link ExecutionIsolationStrategy#THREAD} this defaults to using {@link Schedulers#threadPoolForComputation()} for callbacks.</li>
+     * <li>When using {@link ExecutionIsolationStrategy#THREAD} this defaults to using {@link Schedulers#computation()} for callbacks.</li>
      * <li>When using {@link ExecutionIsolationStrategy#SEMAPHORE} this defaults to using {@link Schedulers#immediate()} for callbacks.</li>
      * </ul>
-     * Use {@link HystrixCommand#toObservable(rx.Scheduler)} or {@link HystrixCollapser#toObservable(rx.Scheduler)} to schedule the callback differently.
      * <p>
      * See https://github.com/ReactiveX/RxJava/wiki for more information.
-     * 
-     * @return {@code Observable<R>} that executes and calls back with the result of {@link #run()} execution or a fallback from {@link #getFallback()} if the command fails for any reason.
+     *
+     * @return {@code Observable<R>} that executes and calls back with the result of the command execution or a fallback if the command execution fails for any reason.
      * @throws HystrixRuntimeException
      *             if a fallback does not exist
      *             <p>
@@ -60,7 +59,7 @@ public interface HystrixObservable<R> extends HystrixInvokable<R> {
      *             if invoked more than once
      */
     public Observable<R> observe();
-    
+
     /**
      * Used for asynchronous execution of command with a callback by subscribing to the {@link Observable}.
      * <p>
@@ -71,14 +70,13 @@ public interface HystrixObservable<R> extends HystrixInvokable<R> {
      * <b>Callback Scheduling</b>
      * <p>
      * <ul>
-     * <li>When using {@link ExecutionIsolationStrategy#THREAD} this defaults to using {@link Schedulers#threadPoolForComputation()} for callbacks.</li>
+     * <li>When using {@link ExecutionIsolationStrategy#THREAD} this defaults to using {@link Schedulers#computation()} for callbacks.</li>
      * <li>When using {@link ExecutionIsolationStrategy#SEMAPHORE} this defaults to using {@link Schedulers#immediate()} for callbacks.</li>
      * </ul>
-     * Use {@link HystrixCommand#toObservable(rx.Scheduler)} or {@link HystrixCollapser#toObservable(rx.Scheduler)} to schedule the callback differently.
      * <p>
      * See https://github.com/ReactiveX/RxJava/wiki for more information.
-     * 
-     * @return {@code Observable<R>} that executes and calls back with the result of {@link #run()} execution or a fallback from {@link #getFallback()} if the command fails for any reason.
+     *
+     * @return {@code Observable<R>} that executes and calls back with the result of the command execution or a fallback if the command execution fails for any reason.
      * @throws HystrixRuntimeException
      *             if a fallback does not exist
      *             <p>

diff --git a/hystrix-core/src/main/java/com/netflix/hystrix/HystrixObservableCollapser.java b/hystrix-core/src/main/java/com/netflix/hystrix/HystrixObservableCollapser.java
@@ -318,7 +318,7 @@ protected Collection<Collection<CollapsedRequest<ResponseType, RequestArgumentTy
      * <p>
      * This allows setting an exception (via {@link CollapsedRequest#setException(Exception)}) or a fallback response (via {@link CollapsedRequest#setResponse(Object)}).
      * 
-     * @param CollapsedRequest
+     * @param r {@link CollapsedRequest}
      *            that needs a response or exception set on it.
      */
     protected abstract void onMissingResponse(CollapsedRequest<ResponseType, RequestArgumentType> r);
@@ -335,21 +335,21 @@ protected Collection<Collection<CollapsedRequest<ResponseType, RequestArgumentTy
     /**
      * Used for asynchronous execution with a callback by subscribing to the {@link Observable}.
      * <p>
-     * This eagerly starts execution the same as {@link #queue()} and {@link #execute()}.
+     * This eagerly starts execution the same as {@link HystrixCollapser#queue()} and {@link HystrixCollapser#execute()}.
      * A lazy {@link Observable} can be obtained from {@link #toObservable()}.
      * <p>
      * <b>Callback Scheduling</b>
      * <p>
      * <ul>
-     * <li>When using {@link ExecutionIsolationStrategy#THREAD} this defaults to using {@link Schedulers#threadPoolForComputation()} for callbacks.</li>
+     * <li>When using {@link ExecutionIsolationStrategy#THREAD} this defaults to using {@link Schedulers#computation()} for callbacks.</li>
      * <li>When using {@link ExecutionIsolationStrategy#SEMAPHORE} this defaults to using {@link Schedulers#immediate()} for callbacks.</li>
      * </ul>
      * Use {@link #toObservable(rx.Scheduler)} to schedule the callback differently.
      * <p>
      * See https://github.com/Netflix/RxJava/wiki for more information.
      * 
-     * @return {@code Observable<R>} that executes and calls back with the result of of {@link HystrixCommand}{@code <BatchReturnType>} execution after passing through {@link #mapResponseToRequests}
-     *         to transform the {@code <BatchReturnType>} into {@code <ResponseType>}
+     * @return {@code Observable<R>} that executes and calls back with the result of of {@link HystrixCommand}{@code <BatchReturnType>} execution after mapping
+     *         the {@code <BatchReturnType>} into {@code <ResponseType>}
      */
     public Observable<ResponseType> observe() {
         // us a ReplaySubject to buffer the eagerly subscribed-to Observable
@@ -366,14 +366,14 @@ public Observable<ResponseType> observe() {
      * <b>Callback Scheduling</b>
      * <p>
      * <ul>
-     * <li>When using {@link ExecutionIsolationStrategy#THREAD} this defaults to using {@link Schedulers#threadPoolForComputation()} for callbacks.</li>
+     * <li>When using {@link ExecutionIsolationStrategy#THREAD} this defaults to using {@link Schedulers#computation()} for callbacks.</li>
      * <li>When using {@link ExecutionIsolationStrategy#SEMAPHORE} this defaults to using {@link Schedulers#immediate()} for callbacks.</li>
      * </ul>
      * <p>
      * See https://github.com/Netflix/RxJava/wiki for more information.
      * 
-     * @return {@code Observable<R>} that lazily executes and calls back with the result of of {@link HystrixCommand}{@code <BatchReturnType>} execution after passing through
-     *         {@link #mapResponseToRequests} to transform the {@code <BatchReturnType>} into {@code <ResponseType>}
+     * @return {@code Observable<R>} that lazily executes and calls back with the result of of {@link HystrixCommand}{@code <BatchReturnType>} execution after mapping the
+     * {@code <BatchReturnType>} into {@code <ResponseType>}
      */
     public Observable<ResponseType> toObservable() {
         // when we callback with the data we want to do the work
@@ -388,8 +388,8 @@ public Observable<ResponseType> toObservable() {
      * 
      * @param observeOn
      *            The {@link Scheduler} to execute callbacks on.
-     * @return {@code Observable<R>} that lazily executes and calls back with the result of of {@link HystrixCommand}{@code <BatchReturnType>} execution after passing through
-     *         {@link #mapResponseToRequests} to transform the {@code <BatchReturnType>} into {@code <ResponseType>}
+     * @return {@code Observable<R>} that lazily executes and calls back with the result of of {@link HystrixCommand}{@code <BatchReturnType>} execution after mapping the
+     * {@code <BatchReturnType>} into {@code <ResponseType>}
      */
     public Observable<ResponseType> toObservable(Scheduler observeOn) {
 

diff --git a/hystrix-core/src/main/java/com/netflix/hystrix/HystrixObservableCommand.java b/hystrix-core/src/main/java/com/netflix/hystrix/HystrixObservableCommand.java
@@ -69,7 +69,7 @@ protected boolean shouldOutputOnNextEvents() {
      * <p>
      * Do not create multiple {@link HystrixObservableCommand} implementations with the same {@link HystrixCommandKey} but different injected default properties as the first instantiated will win.
      * <p>
-     * Properties passed in via {@link Setter#andCommandPropertiesDefaults} or {@link Setter#andThreadPoolPropertiesDefaults} are cached for the given {@link HystrixCommandKey} for the life of the JVM
+     * Properties passed in via {@link Setter#andCommandPropertiesDefaults} are cached for the given {@link HystrixCommandKey} for the life of the JVM
      * or until {@link Hystrix#reset()} is called. Dynamic properties allow runtime changes. Read more on the <a href="https://github.com/Netflix/Hystrix/wiki/Configuration">Hystrix Wiki</a>.
      * 
      * @param setter
@@ -194,14 +194,14 @@ private HystrixCommandProperties.Setter setDefaults(HystrixCommandProperties.Set
     }
 
     /**
-     * Implement this method with code to be executed when {@link #execute()} or {@link #queue()} are invoked.
+     * Implement this method with code to be executed when {@link #observe()} or {@link #toObservable()} are invoked.
      * 
      * @return R response type
      */
     protected abstract Observable<R> construct();
 
     /**
-     * If {@link #execute()} or {@link #queue()} fails in any way then this method will be invoked to provide an opportunity to return a fallback response.
+     * If {@link #observe()} or {@link #toObservable()} fails in any way then this method will be invoked to provide an opportunity to return a fallback response.
      * <p>
      * This should do work that does not require network transport to produce.
      * <p>