Explain, rename, etc.

Author: akarnokd

DESIGN.md

@@ -325,24 +325,61 @@ In the addition of the previous rules, an operator for `Flowable`:
 
 ### Creation
 
-Unlike RxJava 1.x, 2.x base classes are abstract and stateless and generally no longer wrap an `OnSubscribe` callback - this saves allocation in assembly time without limiting the expressiveness. Operator methods and standard factories still live as final on the base classes. 
+Unlike RxJava 1.x, 2.x base classes are to be abstract, stateless and generally no longer wrap an `OnSubscribe` callback - this saves allocation in assembly time without limiting the expressiveness. Operator methods and standard factories still live as final on the base classes.
+
+Instead of the indirection of an `OnSubscribe` and `lift`, operators are to be implemented by extending the base classes. For example, the `map`
+operator will look like this:
+
+```java
+public final class FlowableMap<T, R> extends Flowable<R> {
+    
+    final Flowable<? extends T> source;
+    
+    final Function<? super T, ? extends R> mapper;
+    
+    public FlowableMap(Flowable<? extends T> source, Function<? super T, ? extends R> mapper) {
+        this.source = source;
+        this.mapper = mapper;
+    }
+    
+    @Override
+    protected void subscribeActual(Subscriber<? super R> subscriber) {
+        source.subscribe(new FlowableMapSubscriber<T, R>(subscriber, mapper));
+    }
+    
+    static final class FlowableMapSubscriber<T, R> implements Subscriber<T>, Subscription {
+        // ...
+    }
+}
+``` 
 
 Since Java still doesn't have extension methods, "adding" more operators can only happen through helper methods such as `lift(C -> C)` and `compose(R -> P)` where `C` is the default consumer type (i.e., `rs.Subscriber`), `R` is the base type (i.e., `Flowable`) and `P` is the base interface (i.e., `rs.Publisher`). As before, the library itself may gain or lose standard operators and/or overloads through the same community process.
 
-In concert, `create(OnSubscribe)` will not be available; standard operators extend the base types directly. The conversion of other RS-based libraries will happen through the `Flowable.wrap()` static method. 
+In concert, `create(OnSubscribe)` will not be available; standard operators extend the base types directly. The conversion of other RS-based libraries will happen through the `Flowable.wrap(Publisher<T>)` static method. 
 
 (*The unfortunate effect of `create` in 1.x was the ignorance of the Observable contract and beginner's first choice as an entry point. We can't eliminate this path since `rs.Publisher` is a single method functional interface that can be implemented just as badly.*)
 
 Therefore, new standard factory methods will try to address the common entry point requirements: 
-  - `create(SyncOnSubscribe)` to safe, synchronous generation of signals, one-by-one
-  - `create(AsyncOnSubscribe)` to batch-create signals based on request patterns
+  - `create(SyncGenerator<T, S>)` to safe, synchronous generation of signals, one-by-one
+  - `create(AsyncGenerator<T, S>)` to batch-create signals based on request patterns
   - `create(Consumer<? super SingleEmitter<T>>)` to relay a single value or error from other reactive sources (i.e., addListener callbacks)
-  -  `create(Consumer<? super FlowEmitter<T>>)` to relay multiple values or error from multi-valued reactive-sources (i.e., button-clicks) while also give flow control options right there (buffer, drop, error, etc.).
+  - `create(Consumer<? super FlowEmitter<T>>)` to relay multiple values or error from multi-valued reactive-sources (i.e., button-clicks) while also give flow control options right there (buffer, drop, error, etc.).
+  - `create(Consumer<? super CompletionEmitter>)` signal a completion or error from valueless reactive sources
+
+The following table lists where these create methods will be available in respect of the base types:
+
+| Method | Flowable | Observable | Single | Completable |
+|--------|----------|------------|--------|-------------|
+| `create(SyncGenerator<T, S>)` | Yes | Yes | No | No |
+| `create(AsyncOnSubscribe<T, S>)` | Yes | No | No | No |
+| `create(Consumer<? super SingleEmitter<T>>)` | Yes | Yes | Yes | No |
+| `create(Consumer<? super FlowEmitter<T>>)` | Yes | Yes | Yes | No |
+| `create(Consumer<? super CompletionEmitter)>` | Yes | Yes | No | Yes |
 
 The first two `create` methods take an implementation of an interface which provides state and the generator methods:
 
 ```java
-interface SyncOnSubscribe<T, S> {
+interface SyncGenerator<T, S> {
 
     S createState();
 
@@ -351,7 +388,7 @@ interface SyncOnSubscribe<T, S> {
     void disposeState(S state);
 }
 
-interface AsyncOnSubscribe<T, S> {
+interface AsyncGenerator<T, S> {
 
     S createState();
 
@@ -361,7 +398,7 @@ interface AsyncOnSubscribe<T, S> {
 }
 ```
 
-These latter two `create` methods will provide the following interaction interfaces to the `java.util.function.Consumer`:
+These latter three `create` methods will provide the following interaction interfaces to the `java.util.function.Consumer`:
 
 ```java
 interface SingleEmitter<T> {
@@ -399,6 +436,19 @@ interface FlowEmitter<T> {
     void setBackpressureHandling(BackpressureHandling mode);
 
 }
+
+interface CompletableEmitter<T> {
+
+    complete();
+    
+    fail(Throwable error);
+    
+    stop();
+    
+    setDisposable(Disposable d);
+    
+}
+
 ```
 
 By extending the base classes, operator implementations would loose the tracking/wrapping features of 1.x. To avoid this, the methods `subscribe(C)` will be final and operators have to implement a protected `subscribeActual` (or any other reasonable name).