3.x: Javadocs package-info made nicer, update README regarding Java 8 (#6778)

Author: akarnokd

README.md

@@ -11,10 +11,10 @@ It extends the [observer pattern](http://en.wikipedia.org/wiki/Observer_pattern)
 #### Version 3.x ([Javadoc](http://reactivex.io/RxJava/3.x/javadoc/))
 
 - single dependency: [Reactive-Streams](https://github.com/reactive-streams/reactive-streams-jvm)  
-- continued support for Java 6+ & [Android](https://github.com/ReactiveX/RxAndroid) 2.3+
+- Java 8+ ([Android](https://github.com/ReactiveX/RxAndroid) desugar friendly)
+- Java 8 lambda-friendly API
 - fixed API mistakes and many limits of RxJava 2
 - intended to be a replacement for RxJava 2 with relatively few binary incompatible changes
-- Java 8 lambda-friendly API
 - non-opinionated about the source of concurrency (threads, pools, event loops, fibers, actors, etc.)
 - async or synchronous execution
 - virtual time and schedulers for parameterized concurrency
@@ -60,19 +60,6 @@ public class HelloWorld {
 }
 ```
 
-If your platform doesn't support Java 8 lambdas (yet), you have to create an inner class of `Consumer` manually:
-
-```java
-import io.reactivex.rxjava3.functions.Consumer;
-
-Flowable.just("Hello world")
-  .subscribe(new Consumer<String>() {
-      @Override public void accept(String s) {
-          System.out.println(s);
-      }
-  });
-```
-
 Note that RxJava 3 components now live under `io.reactivex.rxjava3` and the base classes and interfaces live under `io.reactivex.rxjava3.core`.
 
 ### Base classes
@@ -557,7 +544,7 @@ Binaries and dependency information for Maven, Ivy, Gradle and others can be fou
 Example for Gradle:
 
 ```groovy
-compile 'io.reactivex.rxjava3:rxjava:x.y.z'
+implementation 'io.reactivex.rxjava3:rxjava:x.y.z'
 ```
 
 and for Maven:
@@ -575,6 +562,8 @@ and for Ivy:
 <dependency org="io.reactivex.rxjava3" name="rxjava" rev="x.y.z" />
 ```
 
+### Snapshots
+
 Snapshots are available via https://oss.jfrog.org/libs-snapshot/io/reactivex/rxjava3/rxjava/
 
 ```groovy
@@ -587,6 +576,8 @@ dependencies {
 }
 ```
 
+JavaDoc snapshots are available at http://reactivex.io/RxJava/3.x/javadoc/snapshot
+
 ## Build
 
 To build:

src/main/java/io/reactivex/rxjava3/annotations/Nullable.java

@@ -19,10 +19,10 @@
 import java.lang.annotation.*;
 
 /**
- * Indicates that a field/parameter/variable/return type may be null.
+ * Indicates that a field/parameter/variable/type parameter/return type may be null.
  */
 @Documented
-@Target(value = {FIELD, METHOD, PARAMETER, LOCAL_VARIABLE})
+@Target(value = {FIELD, METHOD, PARAMETER, LOCAL_VARIABLE, TYPE_PARAMETER, TYPE_USE})
 @Retention(value = CLASS)
 public @interface Nullable { }
 

src/main/java/io/reactivex/rxjava3/annotations/package-info.java

@@ -15,6 +15,8 @@
  */
 
 /**
- * Annotations for indicating experimental and beta operators, classes, methods, types or fields.
+ * Annotations for indicating operator behavior, API stability
+ * ({@link io.reactivex.rxjava3.annotations.Experimental @Experimental} and {@link io.reactivex.rxjava3.annotations.Beta @Beta}) and
+ * nullability indicators ({@link io.reactivex.rxjava3.annotations.Nullable Nullable} and {@link io.reactivex.rxjava3.annotations.NonNull NonNull}).
  */
 package io.reactivex.rxjava3.annotations;

src/main/java/io/reactivex/rxjava3/disposables/package-info.java

@@ -15,8 +15,8 @@
  */
 
 /**
- * Default implementations for Disposable-based resource management
- * (Disposable container types) and utility classes to construct
- * Disposables from callbacks and other types.
+ * Default implementations for {@link io.reactivex.rxjava3.disposables.Disposable Disposable}-based resource management
+ * ({@code Disposable} container types) and utility classes to construct
+ * {@link io.reactivex.rxjava3.disposables.Disposables Disposables} from callbacks and other types.
  */
 package io.reactivex.rxjava3.disposables;

src/main/java/io/reactivex/rxjava3/exceptions/package-info.java

@@ -15,7 +15,10 @@
  */
 
 /**
- * Exception handling utilities, safe subscriber exception classes,
- * lifecycle exception classes.
+ * Exception handling utilities ({@link io.reactivex.rxjava3.exceptions.Exceptions Exceptions}),
+ * composite exception container ({@link io.reactivex.rxjava3.exceptions.CompositeException CompositeException}) and
+ * various lifecycle-reladed ({@link io.reactivex.rxjava3.exceptions.MissingBackpressureException UndeliverableException})
+ * and behavior-violation exception types ({@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException},
+ * {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException MissingBackpressureException}).
  */
 package io.reactivex.rxjava3.exceptions;

src/main/java/io/reactivex/rxjava3/observers/package-info.java

@@ -15,10 +15,44 @@
  */
 
 /**
- * Default wrappers and implementations for Observer-based consumer classes and interfaces,
+ * Default wrappers and implementations for observer-based consumer classes and interfaces,
  * including disposable and resource-tracking variants and
- * the {@link io.reactivex.rxjava3.observers.TestObserver} that allows unit testing
- * {@link io.reactivex.rxjava3.core.Observable}-, {@link io.reactivex.rxjava3.core.Single}-, {@link io.reactivex.rxjava3.core.Maybe}-
- * and {@link io.reactivex.rxjava3.core.Completable}-based flows.
+ * the {@link io.reactivex.rxjava3.observers.TestObserver TestObserver} that allows unit testing
+ * {@link io.reactivex.rxjava3.core.Observable Observable}-, {@link io.reactivex.rxjava3.core.Single Single}-,
+ * {@link io.reactivex.rxjava3.core.Maybe Maybe}- and {@link io.reactivex.rxjava3.core.Completable Completable}-based flows.
+ * <p>
+ * Available observer variants
+ * <br>
+ * <table border="1" style="border-collapse: collapse;" summary="The available observer types.">
+ * <tr><td><b>Reactive type</b></td><td><b>Base interface</b></td><td><b>Simple</b></td><td><b>Disposable</b></td><td><b>Resource</b></td></tr>
+ * <tr>
+ *     <td>{@link io.reactivex.rxjava3.core.Observable Observable}</td>
+ *     <td>{@link io.reactivex.rxjava3.core.Observer Observer}</td>
+ *     <td>{@link io.reactivex.rxjava3.observers.DefaultObserver DefaultObserver}</td>
+ *     <td>{@link io.reactivex.rxjava3.observers.DisposableObserver DisposableObserver}</td>
+ *     <td>{@link io.reactivex.rxjava3.observers.ResourceObserver DisposableObserver}</td>
+ * </tr>
+ * <tr>
+ *     <td>{@link io.reactivex.rxjava3.core.Maybe Maybe}</td>
+ *     <td>{@link io.reactivex.rxjava3.core.MaybeObserver MaybeObserver}</td>
+ *     <td>N/A</td>
+ *     <td>{@link io.reactivex.rxjava3.observers.DisposableMaybeObserver DisposableMaybeObserver}</td>
+ *     <td>{@link io.reactivex.rxjava3.observers.ResourceMaybeObserver DisposableMaybeObserver}</td>
+ * </tr>
+ * <tr>
+ *     <td>{@link io.reactivex.rxjava3.core.Single Single}</td>
+ *     <td>{@link io.reactivex.rxjava3.core.SingleObserver SingleObserver}</td>
+ *     <td>N/A</td>
+ *     <td>{@link io.reactivex.rxjava3.observers.DisposableSingleObserver DisposableSingleObserver}</td>
+ *     <td>{@link io.reactivex.rxjava3.observers.ResourceSingleObserver DisposableSingleObserver}</td>
+ * </tr>
+ * <tr>
+ *     <td>{@link io.reactivex.rxjava3.core.Completable Completable}</td>
+ *     <td>{@link io.reactivex.rxjava3.core.CompletableObserver CompletableObserver}</td>
+ *     <td>N/A</td>
+ *     <td>{@link io.reactivex.rxjava3.observers.DisposableCompletableObserver DisposableCompletableObserver}</td>
+ *     <td>{@link io.reactivex.rxjava3.observers.ResourceCompletableObserver DisposableCompletableObserver}</td>
+ * </tr>
+ * </table>
  */
 package io.reactivex.rxjava3.observers;

src/main/java/io/reactivex/rxjava3/subjects/package-info.java

@@ -15,7 +15,7 @@
  */
 
 /**
- * Classes representing so-called hot sources, aka subjects, that implement a base reactive class and
+ * Classes representing so-called hot sources, aka <strong>subjects</strong>, that implement a base reactive class and
  * the respective consumer type at once to allow forms of multicasting events to multiple
  * consumers as well as consuming another base reactive type of their kind.
  * <p>

src/main/java/io/reactivex/rxjava3/subscribers/package-info.java

@@ -15,9 +15,10 @@
  */
 
 /**
- * Default wrappers and implementations for Subscriber-based consumer classes and interfaces,
- * including disposable and resource-tracking variants and
- * the {@link io.reactivex.rxjava3.subscribers.TestSubscriber} that allows unit testing
- * {@link io.reactivex.rxjava3.core.Flowable}-based flows.
+ * Default wrappers and implementations for {@link org.reactivestreams.Subscriber Subscriber}-based consumer classes and interfaces,
+ * including disposable ({@link io.reactivex.rxjava3.subscribers.DisposableSubscriber DisposableSubscriber}) and resource-tracking
+ * ({@link io.reactivex.rxjava3.subscribers.ResourceSubscriber ResourceSubscriber})
+ * variants and the {@link io.reactivex.rxjava3.subscribers.TestSubscriber TestSubscriber} that allows unit testing
+ * {@link io.reactivex.rxjava3.core.Flowable Flowable}-based flows.
  */
 package io.reactivex.rxjava3.subscribers;