Merge pull request #479 from adamsp/patch-1

Clarify examples in Warnings.md

Documentation/Warnings.md

@@ -3,7 +3,7 @@ Warnings
 
 ### <a name="unused-disposable"></a>Unused disposable (unused-disposable)
 
-The same is valid for `subscribe*`, `bind*` and `drive*` family of functions that return `Disposable`.
+The following is valid for the `subscribe*`, `bind*` and `drive*` family of functions that return `Disposable`.
 
 Warning is probably presented in a context similar to this one:
 
@@ -21,9 +21,9 @@ xs
   })  
 ```
 
-`subscribe` function returns a subscription `Disposable` that can be used to cancel computation and free resources.
+The `subscribe` function returns a subscription `Disposable` that can be used to cancel computation and free resources.
 
-Preferred way of terminating these fluent calls is by using `.addDisposableTo(disposeBag)` or in some equivalent way.
+The preferred way of terminating these fluent calls is by using a `DisposeBag`, either through chaining a call to `.addDisposableTo(disposeBag)` or by adding the disposable directly to the bag.
 
 ```Swift
 let xs: Observable<E> ....
@@ -41,13 +41,11 @@ xs
   .addDisposableTo(disposeBag) // <--- note `addDisposableTo`
 ```
 
-When `disposeBag` gets deallocated, subscription will be automatically disposed.
+When `disposeBag` gets deallocated, the disposables contained in it will be automatically disposed.
 
-In case `xs` terminates in a predictable way with `Completed` or `Error` message, not handling subscription `Disposable` won't leak any resources, but it's still preferred way because in that way element computation is terminated at predictable moment.
+In the case where `xs` terminates in a predictable way with either a `Completed` or `Error` message, not handling the subscription `Disposable` won't leak any resources. However, even in this case, using a dispose bag is still the preferred way to handle subscription disposables. It ensures that element computation is always terminated at a predictable moment, and makes your code robust and future proof because resources will be properly disposed even if the implementation of `xs` changes.
 
-That will also make your code robust and future proof because resources will be properly disposed even if `xs` implementation changes.
-
-Another way to make sure subscriptions and resources are tied with the lifetime of some object is by using `takeUntil` operator.
+Another way to make sure subscriptions and resources are tied with the lifetime of some object is by using the `takeUntil` operator.
 
 ```Swift
 let xs: Observable<E> ....
@@ -57,7 +55,7 @@ _ = xs
   .filter { ... }
   .map { ... }
   .switchLatest()
-  .takeUntil(someObject.rx_dellocated) // <-- note the `takeUntil` operator
+  .takeUntil(someObject.rx_deallocated) // <-- note the `takeUntil` operator
   .subscribe(onNext: {
     ...
   }, onError: {
@@ -69,7 +67,6 @@ If ignoring the subscription `Disposable` is desired behavior, this is how to si
 
 ```Swift
 let xs: Observable<E> ....
-let disposeBag = DisposeBag()
 
 _ = xs // <-- note the underscore
   .filter { ... }
@@ -94,9 +91,9 @@ xs
   .map { ... }
 ```
 
-This code defines observable sequence that is filtered and mapped `xs` sequence but then ignores the result.
+This code defines an observable sequence that is filtered and mapped from the `xs` sequence but then ignores the result.
 
-Since this code just defines an observable sequence and then ignores it, it doesn't actually do nothing and it's pretty much useless.
+Since this code just defines an observable sequence and then ignores it, it doesn't actually do anything.
 
 Your intention was probably to either store the observable sequence definition and use it later ...
 
@@ -118,7 +115,8 @@ xs
   .filter { ... }
   .map { ... }
   .subscribeNext { nextElement in       // <-- note the `subscribe*` method
-    ... probably print or something
+    // use the element
+    print(nextElement)
   }
   .addDisposableTo(disposeBag)
 ```