Refresh Documentation ahead of new release (#28)

README.md

@@ -21,17 +21,17 @@
     </a>
 </p>
 
-NetworkReachability is a replacement for Apple's [SystemConfiguration](https://developer.apple.com/documentation/systemconfiguration) [Network Reachability APIs](https://developer.apple.com/documentation/systemconfiguration/scnetworkreachability?language=swift). Because these APIs were originally written in C, they are old and cumbersome to use from Swift. In 2018, Apple added the [Network](https://developer.apple.com/documentation/network) framework which introduced the [`NWPathMonitor`](https://developer.apple.com/documentation/network/nwpathmonitor) class. This API addressed some of the problems with [`SCNetworkReachability`](https://developer.apple.com/documentation/systemconfiguration/scnetworkreachability?language=swift), but was still cumbersome to integrate into many commonly used app patterns. NetworkReachability wraps both these APIs in an easy to use Swift wrapper with similar interfaces and features sthat will be familiar to most iOS developers.
+NetworkReachability is a replacement for Apple's [SystemConfiguration](https://developer.apple.com/documentation/systemconfiguration) [Network Reachability APIs](https://developer.apple.com/documentation/systemconfiguration/scnetworkreachability?language=swift). Because these APIs were originally written in C, they are quite old and cumbersome to use from Swift. In 2018, Apple added the [Network](https://developer.apple.com/documentation/network) framework which introduced the [`NWPathMonitor`](https://developer.apple.com/documentation/network/nwpathmonitor) class. This API addressed some of the problems with [`SCNetworkReachability`](https://developer.apple.com/documentation/systemconfiguration/scnetworkreachability?language=swift), but was still cumbersome to integrate into many commonly used app patterns. NetworkReachability wraps both these APIs in easy to use Swift wrappers with similar interfaces and features that will be familiar to most iOS developers. Using NetworkReachablity, you can easily integrate reachability observation into your app's pipeline using just a few lines of code.
 
 NetworkReachability supports synchronous reachability queries, as well as constant asynchronous reachability observation via the following mechanisms:
 
 * [Delegation](https://developer.apple.com/library/archive/documentation/General/Conceptual/DevPedia-CocoaCore/Delegation.html)
 * [Closures](https://docs.swift.org/swift-book/LanguageGuide/Closures.html)
 * [NotificationCenter](https://developer.apple.com/documentation/foundation/notificationcenter)
-* [Swift Structured Concurrency](https://docs.swift.org/swift-book/LanguageGuide/Concurrency.html)
+* [Swift Concurrency](https://docs.swift.org/swift-book/LanguageGuide/Concurrency.html)
 * [Combine](https://developer.apple.com/documentation/combine)
 
-NetworkReachability also has bindings for [RxSwift](https://github.com/ReactiveX/RxSwift) with an optional additional package: [NetworkReachabilityRxSwift](https://github.com/vsanthanam/NetworkReachabilityRxSwift). This optional package exists so that you can safely depend on NetworkReachability without also depending on RxSwift if you don't need to. NetworkReachability itself has no non-apple dependencies.
+NetworkReachability supports [RxSwift](https://github.com/ReactiveX/RxSwift) bindings with an optional additional package: [NetworkReachabilityRxSwift](https://github.com/vsanthanam/NetworkReachabilityRxSwift). This optional package exists so that you can safely depend on NetworkReachability without also depending on RxSwift if you don't need to. **NetworkReachability itself has no non-apple dependencies.**
 
 ## Installation
 

Sources/NetworkReachability/API/NetworkMonitor/NetworkMonitor.swift

@@ -73,15 +73,15 @@ import Network
 /// - ``networkPathUpdates(requiringInterfaceType:)``
 /// - ``networkPathUpdates(prohibitingInterfaceTypes:)``
 ///
-/// ### NotificationCenter
+/// ### Notifications
 ///
 /// - ``networkPathChangedNotificationName``
 ///
 /// ### Combine
 ///
 /// - ``networkPathPublisher``
-/// - ``networkPathUpdates(requiringInterfaceType:)``
-/// - ``networkPathUpdates(prohibitingInterfaceTypes:)``
+/// - ``networkPathPublisher(requiringInterfaceType:)``
+/// - ``networkPathPublisher(prohibitingInterfaceTypes:)``
 /// - ``Publisher``
 @available(macOS 10.14, iOS 12.0, watchOS 5.0, tvOS 12.0, *)
 public final class NetworkMonitor {
@@ -237,13 +237,15 @@ public final class NetworkMonitor {
     /// See ``NetworkMonitorDelegate`` for more information
     ///
     /// - Tip: The delegate only recieves status changes that occured after it was assigned. To ensure that the delegate recieves every network path change, pass in the delegate on initialization of the monitor.
+    ///
+    /// - Important: Instances of ``NetworkMonitor`` will perform delegate callbacks on the main thread.
     public weak var delegate: (any NetworkMonitorDelegate)?
 
     /// The closure used to observe reachability updates
     ///
     /// - Tip: The update handler only recieves status changes that occured after it was assigned. To enture that the delegate recieves every network path changes, pass in the delegate on initalization of the monitor.
     ///
-    /// - Note: Instances of ``NetworkMonitor`` will always invoke this closure the main thread.
+    /// - Important: Instances of ``NetworkMonitor`` will always invoke this closure the main thread.
     public private(set) var updateHandler: UpdateHandler?
 
     /// The currently available network path observed by the network monitor.

Sources/NetworkReachability/API/ReachabilityMonitor/ReachabilityMonitor.swift

@@ -57,13 +57,15 @@ import SystemConfiguration
 ///
 /// - ``updateHandler-swift.property``
 /// - ``UpdateHandler-swift.typealias``
+/// - ``Result``
+/// - ``Error``
 ///
 /// ### Swift Concurrency
 ///
 /// - ``reachability``
 /// - ``reachabilityUpdates``
 ///
-/// ### NotificationCenter
+/// ### Notifications
 ///
 /// - ``reachabilityChangedNotificationName``
 ///

Sources/NetworkReachability/NetworkReachability.docc/GettingStarted.md

@@ -0,0 +1,32 @@
+# Getting Started with NetworkReachability
+
+Choose between the two APIs included with NetworkReachability
+
+## Overview
+
+NetworkReachability consists of two main classes, ``NetworkMonitor`` and ``ReachabilityMonitor``
+
+``NetworkMonitor`` is built on Apple's [Network](https://developer.apple.com/documentation/network) framework. As such, it requires iOS 12 and returns [`NWPath`](https://developer.apple.com/documentation/network/nwpath) types.
+
+``ReachabilityMonitor`` is built on [SystemConfiguration](https://developer.apple.com/documentation/systemconfiguration), and returns a ``Reachability`` struct which wraps [``SCNetworkReachabilityFlags``](https://developer.apple.com/documentation/systemconfiguration/scnetworkreachabilityflags)
+
+These APIs are very similar, and can generally be used interchangeably. Like Apple's APIs, ``ReachabilityMonitor`` offers a synchronous & asynchronous APIs, and is capable of throwing errors. ``NetworkMonitor`` monitor is simpler and more powerful, but does not offer a reliable synchronous API.
+
+| API                | Single Value | Observing Values  | Throws Errors | Minimum OS                              |
+| ------------------ | ------------ | ----------------- | ------------- | --------------------------------------- |
+| ``NetworkMonitor`` | Async        | Async             | No            | iOS 12, macOS 10.14, watchOS 5, tvOS 12 |
+| ``Reachability``   | Sync         | Async             | Yes           | iOS 11, macOS 10.13, watchOS 4, tvOS 11 |
+
+I recommend that you use ``NetworkMonitor`` as it both simpler and more robust, unless you need to target iOS 11 or you absolutely need a synchronous API.
+
+Both APIs still offer the same observability mechanisms:
+
+* [Delegation](https://developer.apple.com/library/archive/documentation/General/Conceptual/DevPedia-CocoaCore/Delegation.html)
+* [Closures](https://docs.swift.org/swift-book/LanguageGuide/Closures.html)
+* [NotificationCenter](https://developer.apple.com/documentation/foundation/notificationcenter)
+* [Swift Concurrency](https://docs.swift.org/swift-book/LanguageGuide/Concurrency.html)
+* [Combine](https://developer.apple.com/documentation/combine)
+
+To learn more about ``NetworkMonitor``, see the <doc:NetworkMonitorGuide>.
+
+To learn more about ``ReachabilityMonitor``, see the <doc:ReachabilityMonitorGuide>

Sources/NetworkReachability/NetworkReachability.docc/NetworkMonitorGuide.md

@@ -1,30 +1,36 @@
-# NetworkMonitor Guide
-
-Learn how to observe reachability changes with Swift Concurrency
+# Network Monitor Programming Guide
 
+Learn how to use Network Monitor APIs
 
 ## Overview
 
 The easiest way to use a ``NetworkMonitor`` is to initialize an instance and retain it memory.
 From there you can access the `currentPath` property whenever you need to know the last known network path.
 
 ```swift
+import Network
 import NetworkReachability
 
 let monitor = NetworkMonitor()
 let path = monitor.currentPath
 ```
 
+This synchronous API is easy to use, but `currentPath` isn't always up-to-date and is best used when a monitor instance has been retained in memory for some time. As such, it will be insufficient for many use cases and is not recommended.
 
-This API is simply enough for many uses cases, but ``NetworkMonitor`` offers a few other APIs to observe up-to-date network path changes as they happen.
+Instead, ``NetworkMonitor`` offers a variety of asynchronous APIs for both single value retrieval as well as constant value observation that are gauranteed to offer up-to-date values.
 
 ### Retrieving the current network path
 
-``NetworkMonitor`` allows you to retrieve the last known network path using two asyncronous APIs. Unlike the synchronous API described above which may or may not be up to date, the asynchronous APIs gaurantee you access to an up-to-date value.
+``NetworkMonitor`` allows you to retrieve the last known network path using two asyncronous APIs. Unlike the synchronous API described above which provides values that may or may not be up to date, the asynchronous APIs gaurantee you access to an up-to-date value.
 
 ##### Closures
 
+To asynchronously retrieve the last known network path, you can use the `networkPath(completionHandler:)` static method. The provided closure will be executed exactly once.
+
 ```swift
+import Network
+import NetworkReachability
+
 func updateReachability() {
     NetworkMonitor.networkPath(completionHandler: { (path: NWPath) in 
         // Do something with `path`
@@ -34,7 +40,12 @@ func updateReachability() {
 
 ##### Swift Concurrency
 
+You can also retrieve the last known network path using Swift Concurrency via the `networkPath` static property.
+
 ```swift
+import Network
+import NetworkReachability
+
 func updateReachability() {
     Task {
         let path = await NetworkMonitor.networkPath
@@ -43,12 +54,16 @@ func updateReachability() {
 }
 ```
 
+- Note: This API requires iOS 13, macOS 10.15, tvOS 13, or watchOS 6
+
 ### Observing network path updates
 
 If you need to observe all network path changes, ``NetworkMonitor`` provides several asynchronous APIs that will allow you to integrate network path data into any existing pipeline
 
 ##### Closures
 
+You can use a closure to observe network path updates over time. You can pass in the closure on initialization, or add one later using the `updateHandler` property.
+
 ```swift
 import Network
 import NetworkReachability
@@ -71,8 +86,12 @@ final class MyClass {
 }
 ```
 
+- Important: ``NetworkMonitor`` always calls its update handler on the main thread.
+
 ##### Swift Concurrency
 
+You can use an `AsyncSequence` to observe network path updates over time using Swift Concurrency
+
 ```swift
 import Network
 import NetworkReachability
@@ -97,8 +116,12 @@ final class MyClass {
 }
 ```
 
+- Note: This API requires iOS 13, macOS 10.15, tvOS 13, or watchOS 6
+
 ##### Delegation
 
+You can use ``NetworkMonitorDelegate`` to recieve callbacks when the network path changes. You can pass in a delegate object when the monitor is initialized, or you can assign one later.
+
 ```swift
 import Network
 import NetworkReachability
@@ -116,21 +139,28 @@ final class MyClass: NetworkMonitorDelegate {
         monitor = nil
     }
 
+    // MARK: - NetworkMonitorDelegate
+
     func networkMonitor(_ monitor: NetworkMonitor, didUpdateNetworkPath networkPath: NWPath) {
         // Do something with `networkPath`
     }
 
 }
 ```
 
+- Important: ``NetworkMonitor`` always executes delegate calbacks on the main thread.
+
 ##### NotificationCenter
 
+If you have retained an instance of ``NetworkMonitor`` in memory, but do not have access to it in the part of your code that needs network path updates, you can 
+observe network path changes by observing notifications with the name `Notification.Name.networkPathChanged` on the default notification center. The notification's `.object` property will contain the ``NetworkMonitor``. From there, you can use `currentPath` property of the monitor, which you now know will be up-to-date thanks to the notification.
+
 ```swift
 import Foundation
 import Network
 import NetworkReachability
 
-final class MyClass: NetworkMonitorDelegate {
+final class MyClass {
 
     var monitor: NetworkMonitor?
 
@@ -161,8 +191,12 @@ final class MyClass: NetworkMonitorDelegate {
 }
 ```
 
+- Important: ``NetworkMonitor`` posts notifications on the main thread.
+
 ##### Combine
 
+You can observe network path changes using a [Combine](https://developer.apple.com/documentation/combine) with the `networkPathPublisher` static property.
+
 ```swift
 import Combine
 import Network
@@ -191,3 +225,5 @@ final class MyClass {
     }
 }
 ```
+
+- Note: This API requires iOS 13, macOS 10.15, tvOS 13, or watchOS 6

Sources/NetworkReachability/NetworkReachability.docc/NetworkReachability.md

@@ -3,30 +3,25 @@
 A Swift replacement for `SCNetworkReachability` & `NWPathMonitor` with support for structured concurrency.
 
 NetworkReachability is a replacement for Apple's [SystemConfiguration](https://developer.apple.com/documentation/systemconfiguration) [Network Reachability APIs](https://developer.apple.com/documentation/systemconfiguration/scnetworkreachability?language=swift). Because these APIs were originally written in C, they are old and cumbersome to use from Swift. In 2018, Apple added the [Network](https://developer.apple.com/documentation/network) framework which introduced the [`NWPathMonitor`](https://developer.apple.com/documentation/network/nwpathmonitor) class. This API addressed some of the problems with [`SCNetworkReachability`](https://developer.apple.com/documentation/systemconfiguration/scnetworkreachability?language=swift), but was still cumbersome to integrate into many commonly used app patterns. NetworkReachability wraps both these APIs in an easy to use Swift wrapper with similar interfaces and features sthat will be familiar to most iOS developers.
-NetworkReachability supports with the following Apple platform releases:
-
-* iOS 11.0 - 15.x
-* macOS 10.13 - 12.x
-* tvOS 11.0 - 15.x
-* watchOS 4.0 - 8.x
 
 ## Usage
 
-To determine the current reachability status. Initialize an instance of ``ReachabilityMonitor`` or ``NetworkMonitor`` and retain it in memory. You can also pass in an optional delegate or update handler to recieve reachability status updates on the main thread. Both classes also fire notifications through `NotificationCenter.default`.
+To determine the current reachability status. Initialize an instance of ``ReachabilityMonitor`` or ``NetworkMonitor`` and retain it in memory. Both classes support a number of observability mechanisms and should be easy to integrate into your data pipelines.
 
 ## Essentials
 
+- <doc:GettingStarted>
 - <doc:NetworkMonitorGuide>
 - <doc:ReachabilityMonitorGuide>
 
 ## Topics
 
-### Network Observation
+### Network Monitor
 
 - ``NetworkMonitor``
 - ``NetworkMonitorDelegate``
 
-### Legacy Observation
+### Reachability Monitor
 
 - ``ReachabilityMonitor``
 - ``ReachabilityMonitorDelegate``