Skip to content

Commit

Permalink
Merge pull request Netflix#706 from mattrjacobs/fix-javadoc-generation
Browse files Browse the repository at this point in the history
Fix Javadoc generation and some Javadoc warnings
  • Loading branch information
mattrjacobs committed Mar 6, 2015
2 parents 1377edd + 17b2cdf commit 5d1874b
Show file tree
Hide file tree
Showing 6 changed files with 32 additions and 38 deletions.
7 changes: 2 additions & 5 deletions hystrix-core/build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
*/
Expand Down Expand Up @@ -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}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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) {

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand Down

0 comments on commit 5d1874b

Please sign in to comment.