Skip to content

3.x: Improve Javadocs of Completable and some others #6809

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 1, 2020
Merged

3.x: Improve Javadocs of Completable and some others #6809

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1,092 changes: 566 additions & 526 deletions src/main/java/io/reactivex/rxjava3/core/Completable.java
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion src/main/java/io/reactivex/rxjava3/core/Observable.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5261,7 +5261,7 @@ public final Iterable<T> blockingIterable() {
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public final Iterable<T> blockingIterable(int capacityHint) {
ObjectHelper.verifyPositive(capacityHint, "bufferSize");
ObjectHelper.verifyPositive(capacityHint, "capacityHint");
return new BlockingObservableIterable<>(this, capacityHint);
}

Expand Down
16 changes: 12 additions & 4 deletions src/main/java/io/reactivex/rxjava3/disposables/Disposable.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ public interface Disposable {
* executed exactly once when the {@code Disposable} is disposed.
* @param run the Runnable to wrap
* @return the new Disposable instance
* @throws NullPointerException if {@code run} is {@code null}
* @since 3.0.0
*/
@NonNull
Expand All @@ -52,14 +53,15 @@ static Disposable fromRunnable(@NonNull Runnable run) {
/**
* Construct a {@code Disposable} by wrapping a {@link Action} that is
* executed exactly once when the {@code Disposable} is disposed.
* @param run the Action to wrap
* @param action the Action to wrap
* @return the new Disposable instance
* @throws NullPointerException if {@code action} is {@code null}
* @since 3.0.0
*/
@NonNull
static Disposable fromAction(@NonNull Action run) {
Objects.requireNonNull(run, "run is null");
return new ActionDisposable(run);
static Disposable fromAction(@NonNull Action action) {
Objects.requireNonNull(action, "action is null");
return new ActionDisposable(action);
}

/**
Expand All @@ -69,6 +71,7 @@ static Disposable fromAction(@NonNull Action run) {
* The {@code Future} is cancelled with {@code mayInterruptIfRunning == true}.
* @param future the Future to wrap
* @return the new Disposable instance
* @throws NullPointerException if {@code future} is {@code null}
* @see #fromFuture(Future, boolean)
* @since 3.0.0
*/
Expand All @@ -84,6 +87,7 @@ static Disposable fromFuture(@NonNull Future<?> future) {
* @param future the Future to wrap
* @param allowInterrupt if true, the future cancel happens via {@code Future.cancel(true)}
* @return the new Disposable instance
* @throws NullPointerException if {@code future} is {@code null}
* @since 3.0.0
*/
@NonNull
Expand All @@ -97,6 +101,7 @@ static Disposable fromFuture(@NonNull Future<?> future, boolean allowInterrupt)
* cancelled exactly once when the {@code Disposable} is disposed.
* @param subscription the Runnable to wrap
* @return the new Disposable instance
* @throws NullPointerException if {@code subscription} is {@code null}
* @since 3.0.0
*/
@NonNull
Expand All @@ -110,6 +115,7 @@ static Disposable fromSubscription(@NonNull Subscription subscription) {
* closed exactly once when the {@code Disposable} is disposed.
* @param autoCloseable the AutoCloseable to wrap
* @return the new Disposable instance
* @throws NullPointerException if {@code autoCloseable} is {@code null}
* @since 3.0.0
*/
@NonNull
Expand All @@ -123,10 +129,12 @@ static Disposable fromAutoCloseable(@NonNull AutoCloseable autoCloseable) {
* disposed when the returned {@code AutoCloseable} is closed.
* @param disposable the Disposable instance
* @return the new AutoCloseable instance
* @throws NullPointerException if {@code disposable} is {@code null}
* @since 3.0.0
*/
@NonNull
static AutoCloseable toAutoCloseable(@NonNull Disposable disposable) {
Objects.requireNonNull(disposable, "disposable is null");
return disposable::dispose;
}

Expand Down
2 changes: 2 additions & 0 deletions src/main/java/io/reactivex/rxjava3/flowables/ConnectableFlowable.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,8 @@ public final Flowable<T> refCount(int subscriberCount, long timeout, @NonNull Ti
* @param unit the time unit of the timeout
* @param scheduler the target scheduler to wait on before disconnecting
* @return the new Flowable instance
* @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
* @throws IllegalArgumentException if {@code subscriberCount} is non-positive
* @since 2.2
*/
@CheckReturnValue
Expand Down
2 changes: 2 additions & 0 deletions src/main/java/io/reactivex/rxjava3/observables/ConnectableObservable.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -224,6 +224,8 @@ public final Observable<T> refCount(int subscriberCount, long timeout, @NonNull
* @param unit the time unit of the timeout
* @param scheduler the target scheduler to wait on before disconnecting
* @return the new Observable instance
* @throws IllegalArgumentException if {@code subscriberCount} is non-positive
* @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
* @since 2.2
*/
@CheckReturnValue
Expand Down
1 change: 1 addition & 0 deletions src/main/java/io/reactivex/rxjava3/processors/BehaviorProcessor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,6 +204,7 @@ public static <T> BehaviorProcessor<T> create() {
* the item that will be emitted first to any {@link Subscriber} as long as the
* {@link BehaviorProcessor} has not yet observed any items from its source {@code Observable}
* @return the constructed {@link BehaviorProcessor}
* @throws NullPointerException if {@code defaultValue} is {@code null}
*/
@CheckReturnValue
@NonNull
Expand Down
5 changes: 4 additions & 1 deletion src/main/java/io/reactivex/rxjava3/processors/MulticastProcessor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,10 +192,12 @@ public static <T> MulticastProcessor<T> create(boolean refCount) {
* @param bufferSize the prefetch amount
* @param <T> the input and output value type
* @return the new MulticastProcessor instance
* @throws IllegalArgumentException if {@code bufferSize} is non-positive
*/
@CheckReturnValue
@NonNull
public static <T> MulticastProcessor<T> create(int bufferSize) {
ObjectHelper.verifyPositive(bufferSize, "bufferSize");
return new MulticastProcessor<>(bufferSize, false);
}

Expand All @@ -207,10 +209,12 @@ public static <T> MulticastProcessor<T> create(int bufferSize) {
* is cancelled
* @param <T> the input and output value type
* @return the new MulticastProcessor instance
* @throws IllegalArgumentException if {@code bufferSize} is non-positive
*/
@CheckReturnValue
@NonNull
public static <T> MulticastProcessor<T> create(int bufferSize, boolean refCount) {
ObjectHelper.verifyPositive(bufferSize, "bufferSize");
return new MulticastProcessor<>(bufferSize, refCount);
}

Expand All @@ -223,7 +227,6 @@ public static <T> MulticastProcessor<T> create(int bufferSize, boolean refCount)
*/
@SuppressWarnings("unchecked")
MulticastProcessor(int bufferSize, boolean refCount) {
ObjectHelper.verifyPositive(bufferSize, "bufferSize");
this.bufferSize = bufferSize;
this.limit = bufferSize - (bufferSize >> 2);
this.wip = new AtomicInteger();
Expand Down
9 changes: 7 additions & 2 deletions src/test/java/io/reactivex/rxjava3/validators/JavadocCodesAndLinks.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,11 @@ public void checkFlowable() throws Exception {
checkSource("Flowable");
}

@Test
public void checkCompletable() throws Exception {
checkSource("Completable");
}

static void checkSource(String baseClassName) throws Exception {
File f = TestHelper.findSource(baseClassName);
if (f == null) {
Expand Down Expand Up @@ -346,15 +351,15 @@ static void blankRange(StringBuilder builder, int start, int end) {

"Exception", "Throwable", "NullPointerException", "IllegalStateException", "IllegalArgumentException", "MissingBackpressureException", "UndeliverableException",
"OutOfMemoryError", "StackOverflowError", "NoSuchElementException", "ClassCastException", "CompositeException",
"RuntimeException", "Error", "TimeoutException",
"RuntimeException", "Error", "TimeoutException", "OnErrorNotImplementedException",

"false", "true", "onNext", "onError", "onComplete", "onSuccess", "onSubscribe", "null",

"ConnectableFlowable", "ConnectableObservable", "Subject", "FlowableProcessor", "Processor", "Scheduler",

"Optional", "CompletionStage", "Collector", "Collectors", "Schedulers", "RxJavaPlugins", "CompletableFuture",

"Object", "Integer", "Long", "Boolean", "LongConsumer",
"Object", "Integer", "Long", "Boolean", "LongConsumer", "BooleanSupplier",

"GroupedFlowable", "GroupedObservable", "UnicastSubject", "UnicastProcessor",

Expand Down
145 changes: 37 additions & 108 deletions src/test/java/io/reactivex/rxjava3/validators/JavadocWording.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,65 +317,7 @@ public void flowableDocRefersToFlowableTypes() throws Exception {
}
}

if (m.signature.matches("(?s).*?\\sSingle\\<.*?\\>\\s+\\w+\\(.*")) {
for (String at : AT_RETURN_WORDS) {
int idx = m.javadoc.indexOf(at + "{@code Flowable");
if (idx >= 0) {
e.append("Returns Single but docs return Flowable\r\n at io.reactivex.rxjava3.core.")
.append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
idx = m.javadoc.indexOf(at + "{@code Maybe");
if (idx >= 0) {
e.append("Returns Single but docs return Maybe\r\n at io.reactivex.rxjava3.core.")
.append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
idx = m.javadoc.indexOf(at + "{@code Publisher");
if (idx >= 0) {
e.append("Returns Single but docs return Publisher\r\n at io.reactivex.rxjava3.core.")
.append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
}
}

if (m.signature.matches("(?s).*?\\sMaybe\\<.*\\>\\s+\\w+\\(.*")) {
for (String at : AT_RETURN_WORDS) {
int idx = m.javadoc.indexOf(at + "{@code Flowable");
if (idx >= 0) {
e.append("Returns Maybe but docs return Flowable\r\n at io.reactivex.rxjava3.core.")
.append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
idx = m.javadoc.indexOf(at + "{@code Single");
if (idx >= 0) {
e.append("Returns Maybe but docs return Single\r\n at io.reactivex.rxjava3.core.")
.append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
idx = m.javadoc.indexOf(at + "{@code Publisher");
if (idx >= 0) {
e.append("Returns Maybe but docs return Publisher\r\n at io.reactivex.rxjava3.core.")
.append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
}
}

if (m.signature.matches("(?s).*?\\sCompletable\\s+\\w+\\(.*")) {
for (String at : AT_RETURN_WORDS) {
int idx = m.javadoc.indexOf(at + "{@code Flowable");
if (idx >= 0) {
e.append("Returns Completable but docs return Flowable\r\n at io.reactivex.rxjava3.core.")
.append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
idx = m.javadoc.indexOf(at + "{@code Single");
if (idx >= 0) {
e.append("Returns Completable but docs return Single\r\n at io.reactivex.rxjava3.core.")
.append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
idx = m.javadoc.indexOf(at + "{@code Maybe");
if (idx >= 0) {
e.append("Returns Completable but docs return Maybe\r\n at io.reactivex.rxjava3.core.")
.append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
}
}
checkAtReturnAndSignatureMatch("Flowable", m, e, "Flowable", "Observable", "Maybe", "Single", "Completable");

aOrAn(e, m, "Flowable");
missingClosingDD(e, m, "Flowable");
Expand Down Expand Up @@ -478,55 +420,7 @@ public void observableDocRefersToObservableTypes() throws Exception {
break;
}
}
if (m.signature.matches("(?s).*?\\sSingle\\<.*?\\>\\s+\\w+\\(.*")) {
for (String at : AT_RETURN_WORDS) {
int idx = m.javadoc.indexOf(at + "{@code Observable");
if (idx >= 0) {
e.append("Returns Single but docs return Observable\r\n at io.reactivex.rxjava3.core.")
.append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
idx = m.javadoc.indexOf(at + "{@code Maybe");
if (idx >= 0) {
e.append("Returns Single but docs return Maybe\r\n at io.reactivex.rxjava3.core.")
.append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
}
}

if (m.signature.matches("(?s).*?\\sMaybe\\<.*?\\>\\s+\\w+\\(.*")) {
for (String at : AT_RETURN_WORDS) {
int idx = m.javadoc.indexOf(at + "{@code Observable");
if (idx >= 0) {
e.append("Returns Maybe but docs return Observable\r\n at io.reactivex.rxjava3.core.")
.append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
idx = m.javadoc.indexOf(at + "{@code Single");
if (idx >= 0) {
e.append("Returns Maybe but docs return Single\r\n at io.reactivex.rxjava3.core.")
.append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
}
}

if (m.signature.matches("(?s).*?\\sCompletable\\s+\\w+\\(.*")) {
for (String at : AT_RETURN_WORDS) {
int idx = m.javadoc.indexOf(at + "{@code Observable");
if (idx >= 0) {
e.append("Returns Completable but docs return Observable\r\n at io.reactivex.rxjava3.core.")
.append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
idx = m.javadoc.indexOf(at + "{@code Single");
if (idx >= 0) {
e.append("Returns Completable but docs return Single\r\n at io.reactivex.rxjava3.core.")
.append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
idx = m.javadoc.indexOf(at + "{@code Maybe");
if (idx >= 0) {
e.append("Returns Completable but docs return Maybe\r\n at io.reactivex.rxjava3.core.")
.append("Observable.method(Observable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n");
}
}
}
checkAtReturnAndSignatureMatch("Observable", m, e, "Flowable", "Observable", "Maybe", "Single", "Completable");

aOrAn(e, m, "Observable");
missingClosingDD(e, m, "Observable");
Expand Down Expand Up @@ -890,6 +784,9 @@ public void completableDocRefersToCompletableTypes() throws Exception {
break;
}
}

checkAtReturnAndSignatureMatch("Completable", m, e, "Flowable", "Observable", "Maybe", "Single", "Completable");

aOrAn(e, m, "Completable");
missingClosingDD(e, m, "Completable");
backpressureMentionedWithoutAnnotation(e, m, "Completable");
Expand All @@ -903,6 +800,38 @@ public void completableDocRefersToCompletableTypes() throws Exception {
}
}

static void checkAtReturnAndSignatureMatch(String className, RxMethod m, StringBuilder e, String... types) {
for (String t : types) {
String regex;
if (t.contains("Completable")) {
regex = "(?s).*?\\s" + t + "\\s+\\w+\\(.*";
} else {
regex = "(?s).*?\\s" + t + "\\<.*?\\>\\s+\\w+\\(.*";
}
if (m.signature.matches(regex)) {
for (String at : AT_RETURN_WORDS) {
for (String u : types) {
if (!t.equals(u)) {
int idx = m.javadoc.indexOf(at + "{@code " + u);
if (idx >= 0) {
e.append("Returns ").append(t)
.append(" but docs return ")
.append(u)
.append("\r\n at io.reactivex.rxjava3.core.")
.append(className)
.append(".method(")
.append(className)
.append(".java:")
.append(m.javadocLine + lineNumber(m.javadoc, idx) - 1)
.append(")\r\n\r\n");
}
}
}
}
}
}
}

static void aOrAn(StringBuilder e, RxMethod m, String baseTypeName) {
aOrAn(e, m, " an", "Single", baseTypeName);
aOrAn(e, m, " an", "Maybe", baseTypeName);
Expand Down
Loading