Move PublishSubject usage example from Observable to the Subject

Author: shiki

WooCommerce/Classes/Tools/Observables/Observable.swift

@@ -12,37 +12,6 @@ typealias OnNext<Element> = (Element) -> ()
 /// This class is a pseudo-abstract class. It does not do anything on its own. Use the
 /// subclasses like `PublishSubject` instead.
 ///
-/// This abstract class is meant to be a "readonly" `Observable` to hide the mutable methods
-/// of observables like `PublishSubject`. For example, if we use `PublishSubject` and expose it
-/// in the `ViewModel` like this:
-///
-/// ```
-/// class ViewModel {
-///     let onDataLoaded = PublishSubject<[Items]>()
-/// }
-/// ```
-///
-/// The `ViewController` will be able to access the **mutating** methods of `PublishSubject` like:
-///
-/// ```
-/// // Submit new items. This will ultimately call the `subscribe` callbacks.
-/// viewModel.onDataLoaded.send([Item]())
-/// ```
-///
-/// Ideally, the `ViewController` should only have the `Observable` _interface_ so it only has
-/// access to `subscribe()`. We can do that this way:
-///
-/// ```
-/// class ViewModel {
-///     private let onDataLoadedSubject = PublishSubject<[Items]>()
-///
-///     // Expose a readonly observable
-///     var onDataLoaded: Observable<[Items]> {
-///         onDataLoadedSubject
-///     }
-/// }
-/// ```
-///
 /// See here for more info about Observables:
 ///
 /// - https://developer.apple.com/documentation/combine/publisher

WooCommerce/Classes/Tools/Observables/PublishSubject.swift

@@ -12,6 +12,55 @@ import Foundation
 /// Multiple observers are allowed which makes this a possible replacement for
 /// `NSNotificationCenter` observations.
 ///
+/// ## Example Usage
+///
+/// In a class that you would like to emit values (or events), add the `PublishSubject` defining
+/// the value type:
+///
+/// ```
+/// class PostListViewModel {
+///     /// Calls observers/subscribers whenever the list of Post changes.
+///     private let postsSubject = PublishSubject<[Post]>()
+/// }
+/// ```
+///
+/// Since `PublishSubject` exposes `send()` which makes this a **mutable** Observable, we recommend
+/// exposing only the `Observable<[Post]>` interface:
+///
+/// ```
+/// class PostListViewModel {
+///     private let postsSubject = PublishSubject<[Post]>()
+///
+///     /// The public Observable that the ViewController will subscribe to
+///     var posts: Observable<[Post]> {
+///         postsSubject
+///     }
+/// }
+/// ```
+///
+/// The `ViewController` can then subscribe to the `posts` Observable:
+///
+/// ```
+/// func viewDidLoad() {
+///     viewModel.posts.subscribe { posts in
+///         // do something with posts
+///         tableView.reloadData()
+///     }
+/// }
+/// ```
+///
+/// Whenever the list of post changes, like after fetching from the API, the `ViewModel` can
+/// _notify_ the `ViewController` by updating `postsSubject`:
+///
+/// ```
+/// fetchFromAPI { fetchedPosts
+///     // Notify the observers (e.g. ViewController) that the list of posts have changed
+///     postsSubject.send(fetchedPosts)
+/// }
+/// ```
+///
+/// ## References
+///
 /// See here for info about similar observables in other frameworks:
 ///
 /// - https://developer.apple.com/documentation/combine/passthroughsubject