doing an existing content edit pass while I wait for structural feedback

Author: heckj

docs/aboutthisbook.adoc

@@ -18,9 +18,9 @@ I am working through how to make it available to the widest audience while also
 Joe Heck has broad software engineering development and management experience crossing startups and large companies.
 He works across all the layers of solutions, from architecture, development, validation, deployment, and operations.
 
-Joe has developed projects ranging from mobile and desktop application development to large cloud-based distributed systems.
-He has established development processes, CI and CD pipelines, and developed validation and operational automation for software solutions.
-Joe also builds teams and mentors people to learn, build, validate, deploy and run software services and infrastructure.
+Joe has developed projects ranging from mobile and desktop application development to cloud-based distributed systems.
+He has established teams, development processes, CI and CD pipelines, and developed validation and operational automation.
+Joe also builds and mentors people to learn, build, validate, deploy and run software services and infrastructure.
 
 Joe works extensively with and in open source, contributing and collaborating with a wide variety of open source projects.
 He writes online across a variety of topics at https://rhonabwy.com/.
@@ -35,7 +35,9 @@ He writes online across a variety of topics at https://rhonabwy.com/.
 == Where to get this book
 
 The contents of this book are available as https://heckj.github.io/swiftui-notes/[HTML], https://heckj.github.io/swiftui-notes/using-combine-book.pdf[PDF], and https://heckj.github.io/swiftui-notes/using-combine-book.epub[ePub].
-There is also an Xcode project (`SwiftUI-Notes.xcodeproj`) available from GitHub.
+
+There is also an Xcode project (`SwiftUI-Notes.xcodeproj`) https://github.com/heckj/swiftui-notes[available on GitHub].
+The project includes tests, snippets, and trials used in creating this work.
 
 === Download the project
 

docs/coreconcepts.adoc

@@ -13,6 +13,7 @@ It is also described with two associated types, one for Input and one for Failur
 When you connect a subscriber to a publisher, both types must match: Output to Input, and Failure to Failure.
 You can view this as a series of operations on two types in parallel.
 
+//TODO(heckj) - convert to a diagram
 [source]
 ----
 Publisher source       Subscriber
@@ -28,6 +29,7 @@ You can create chains of these together, for processing, reacting, and transform
 
 I'm calling these composed sequences **pipelines**.
 
+//TODO(heckj) - convert to a diagram
 [source]
 ----
 Publisher source       Operator                          Subscriber
@@ -59,16 +61,20 @@ let _ = Publishers.somePublisher
 ----
 
 When you are viewing a pipeline, or creating one, you can think of it as a sequence of operations linked by the types.
-This pattern will come in handy when you start constructing your own pipelines, as some of operators will either require conformance of a type, or will change the Failure output type.
+This pattern will come in handy when you start constructing your own pipelines.
+With enforced types, there are a number of Combine functions that are created to help with these transformations.
 
-Because the types are enforced, there are a number of Combine functions that are created to help with these transformations.
-Some operators are prefixed with `try` that indicate that they will return an <Error> type.
-In some cases, you may need to define the type being returned in the closure you're providing to the operator.
+Some operators will may require conformance of an input or failure type.
+Other operators may change either or both the failure and output types.
+For example, there are a number of operators that have a similar operator prexed with `try` indicating  they return an <Error> failure type.
 
+//TODO(heckj) change to xref to internal reference for these operators
 An example of this is map and tryMap.
 https://developer.apple.com/documentation/combine/publishers/map[`map`] allows for any combination of Output and Failure type and passes them through.
 https://developer.apple.com/documentation/combine/publishers/trymap['tryMap'] accepts any Input, Failure types, and allows any Output type, but will always output an `<Error>` failure type.
 
+In the example of `map`, you define the output type being returned in the closure you're providing to the operator.
+
 To illustrate changing types within a pipeline, here is a short snippet thsat starts with a publisher that generates `<Int>`, `<Never>` and end with a subscription taking `<String>`, `<Never>`.
 
 [#source-with-callouts]
@@ -108,26 +114,28 @@ In some cases, such as the example above, the compiler is unable to infer the re
 Xcode (11 beta 2) displays this as the error message: `Unable to infer complex closure return type; add explicit type to disambiguate`.
 ****
 
-Combine supports error handling by creating two streams - one for the functional case and one for the error case, and combining them together.
-We will see that in more detail in the <<patterns.adoc#patterns,section on patterns>>.
+You can view Combine publishers, operators, and subscribers as having two parallel types that both need to be aligned - one for the functional case and one for the error case.
+Designing your pipeline is frequently choosing how to convert one or both of those types and the associated data with it.
+
+Examples of this, and some common tasks, are detailed in the <<patterns.adoc#patterns,section on patterns>>.
 
 // force a page break - ignored in HTML rendering
 <<<
 
 [#core-lifecycle]
 == Lifecycle of Publishers and Subscribers
 
-The interals of Combine are all driven by the subscriber.
+The data flow in Combine is driven by, and starts from, the subscriber.
 This is how Combine supports the concept of back pressure.
 
 Internally, Combine supports this with the enumeration https://developer.apple.com/documentation/combine/subscribers/demand[Demand].
-When a subscriber is communicating with a publisher, it requests based on demand.
+When a subscriber is communicating with a publisher, it requests data based on demand.
 This request is what drives calling all the closures up the composed pipeline.
 
 Because subscribers drive the closure execution, it also allows Combine to support cancellation.
 Cancellation can be triggered by the subscriber.
 
-This is all built on subscribers and publishers communicating in a well defined sequence, or lifecycle.
+This is all enabled by subscribers and publishers communicating in a well defined sequence, or lifecycle.
 
 * When the subscriber is attached to a publisher, it starts with a call to `.subscribe(Subscriber)`.
 * The publisher in turn acknowledges the subscription calling `receive(subscription)`.
@@ -147,6 +155,7 @@ The https://developer.apple.com/documentation/combine/publisher[publisher protoc
 
 Combine provides a number of convenience publishers:
 
+//TODO(heckj) - convert to xref to reference sections on these operators
 [cols="3*^"]
 |===
 | https://developer.apple.com/documentation/combine/publishers/empty[`Publishers.Empty`]
@@ -162,10 +171,12 @@ Combine provides a number of convenience publishers:
 | @Published
 
 | @ObjectBinding
+|
+|
 
 |===
 
-Other Apple APIs provide publishers as well
+A number of additional Apple APIs provide publishers as well.
 
 // TODO(heckj): come back and map these to xref's to the reference section when created
 
@@ -352,7 +363,7 @@ Operators can also help with error handling and retry logic, buffering and prefe
 [#core-subjects]
 == Subjects
 
-Subjects are a special case of publisher that also adhere to https://developer.apple.com/documentation/combine/subject[`subject`] protocol.
+Subjects are a special case of publisher that also adhere to the https://developer.apple.com/documentation/combine/subject[`subject`] protocol.
 This protocol requires subjects to have a `.send()` method to allow the developer to send specific values to a subscriber (or pipeline).
 
 Subjects can be used to "inject" values into a stream, by calling the subject's `.send()` method.
@@ -364,31 +375,30 @@ There are two built-in subjects with Combine:
 
 The first is https://developer.apple.com/documentation/combine/currentvaluesubject[`CurrentValueSubject`].
 
-** CurrentValue remembers the current value so that when you attach a subscriber you can see the current value
-
+* CurrentValue remembers the current value so that when a subscriber is attached, it immediately receives the current value.
 
 It is created and initialized with an initial value.
 When a subscriber is connected to it and requests data, the initial value is sent.
 Further calls to `.send()` afterwards will then send those values to any subscribers.
 
 The second is https://developer.apple.com/documentation/combine/passthroughsubject[`PassthroughSubject`].
 
-** Passthrough doesn't maintain any state - just passes through provided values
+* Passthrough doesn't maintain any state - just passes through provided values.
 
 When it is created, only the types are defined.
 When a subscriber is connected and requests data, it will not receive any values until a `.send()` call is invoked.
 Calls to `.send()` will then send values to any subscribers.
 
-PassthroughSubject is extremely useful when writing tests for pipelines, as the sending of any requested data (or a failure) is under test control using the `.send()` function.
+PassthroughSubject is extremely useful when writing tests for pipelines, as sending of any requested data (or a failure) is under the test writer's control using the `.send()` function.
 
 Both CurrentValueSubject and PassthroughSubject are also useful for creating publishers from objects conforming to https://developer.apple.com/documentation/swiftui/bindableobject[`BindableObject`] within SwiftUI.
 
-Subjects can also be useful for fanning out values to multiple subscribers.
+Subjects is also useful for fanning out values to multiple subscribers.
 
 [#core-subscribers]
 == Subscribers
 
-While https://developer.apple.com/documentation/combine/subscriber[`subscriber`] is the protocol used to receive data throughout a pipeline, the Subscriber typically refers to the end of a pipeline.
+While https://developer.apple.com/documentation/combine/subscriber[`subscriber`] is the protocol used to receive data throughout a pipeline, _the Subscriber_ typically refers to the end of a pipeline.
 
 There are two subscribers built-in to Combine: assign and sink.
 
@@ -515,6 +525,5 @@ You may see this in code as an operator, for example:
     .receive(on: RunLoop.main)
 ----
 
-
 // force a page break - ignored in HTML rendering
 <<<

docs/introduction.adoc

@@ -6,7 +6,7 @@ In Apple's words, Combine is:
 [quote]
 a declarative Swift API for processing values over time.
 
-Combine is Apple's take on a functional reactive library, akin to https://github.com/ReactiveX/RxSwift[RxSwift].
+Combine is Apple's take on a functional reactive programming library, akin to https://github.com/ReactiveX/RxSwift[RxSwift].
 RxSwift itself is a port of http://reactivex.io[ReactiveX].
 Apple's framework uses many of the same functional reactive concepts that can be found in other languages and libraries, applying the strongly-typed nature of Swift to their solution.
 
@@ -28,25 +28,29 @@ In addition, functional reactive programming includes functions to split streams
 
 There are many parts of the systems we program that can be viewed as asynchronous streams of information - events, objects, or pieces of data.
 Programming practices defined the Observer pattern for watching a single object, getting notified of changes and updates.
-As this happens over time, you can view the updates as a stream of objects.
+If you view this over time, these updates make up a stream of objects.
+Functional reactive programming, or Combine in this case, allows you to create code that describes what happens when getting data in a stream.
 
 You may want to create logic to watch more than one element that is changing.
 You may also want to include logic that does additional asynchronous operations, some of which may fail.
-You may also want to change the content of the streams based on timing.
-Handling the flow of all these event streams, the timing of all the various pieces, errors when they happen, and coordinating how a system responds to all those events is at the heart of this kind of programming.
+You may also want to change the content of the streams based on timing, or change the timing of the content.
+Handling the flow of these event streams, the timing, errors when they happen, and coordinating how a system responds to all those events is at the heart of this kind of programming.
 
-This solution is particularly effective when programming user interfaces, or for creating pipelines that process and transform data from external sources, or rely on asynchronous APIs.
+A solution based on functional reactive programming is particularly effective when programming user interfaces.
+Or more generally for creating pipelines that process data from external sources or rely on asynchronous APIs.
 
 == Combine specifics
 
 Applying these concepts to a strongly typed language like swift is part of what Apple has created in Combine.
 Combine embeds the concept of back-pressure, which allows the subscriber to control how much information it gets at once and needs to process.
 In addition, it supports efficient operation with the notion of streams that are cancellable and driven primarily by the subscriber.
 
-Combine was also set up to be composed, and Combine is explicitly supported by a couple of Apple's other frameworks.
+Combine is set up to be composed, and includes affordances to integrate existing code to incrementally support adoption.
+
+Combine is supported by a couple of Apple's other frameworks.
 SwiftUI is the obvious example that has the most attention, with both subscriber and publisher elements.
 RealityKit also has publishers that you can use to react to events.
-NotificationCenter, URLSession, and Timer in the Foundation also now include publishers.
+And Foundation has a number of Combine specific additions including NotificationCenter, URLSession, and Timer as publishers.
 
 Any asynchronous operation API _can_ be leveraged with Combine.
 For example, you could use some of the APIs in the Vision framework, composing data flowing to it, and from it, by leveraging Combine.
@@ -59,10 +63,13 @@ Pipeline is not a term that Apple is (yet?) using in its documentation.
 
 == When to use Combine
 
-Combine fits most naturally when you want to set up a system that is "immediately" reactive to a variety of inputs.
+Combine fits most naturally when you want to set up a something that is "immediately" reactive to a variety of inputs.
 User interfaces fit very naturally into this pattern.
 
-The classic examples revolve around the user experience with form validation, where the inputs are text fields and a button for submitting.
+The classic examples in functional reactive programming and user interfaces frequently show form validation, where user events such as changing text fields, taps, or mouse-clicks on UI elements make up the data being streamed.
+Combine takes this quite a bit further, enabling watching of properties, binding to objects, sending and receiving higher level events from UI controls, and supporting integration with almost all of Apple's existing API ecosystem.
+
+Some things you can do with Combine include:
 
 * You can set up pipelines to enable the button for submission only when values entered into the fields are valid.
 * A pipeline can also do asynchronous actions (such as checking with a network service) and using the values returned to choose how and what to update within a view.
@@ -90,7 +97,8 @@ Apple's developer documentation is hosted at https://developer.apple.com/documen
 
 === WWDC content
 
-Apple provides video, slides, and some sample code in sessions from https://developer.apple.com/videos/play/wwdc2019[WWDC 2019]
+Apple provides video, slides, and some sample code in sessions it's developer conferences.
+Details on Combine are primarily from https://developer.apple.com/videos/play/wwdc2019[WWDC 2019].
 
 A number of these introduce and go into some depth on Combine:
 
@@ -100,7 +108,7 @@ A number of these introduce and go into some depth on Combine:
 * https://developer.apple.com/videos/play/wwdc2019/721/[Combine in Practice]
 ** https://devstreaming-cdn.apple.com/videos/wwdc/2019/721ga0kflgr4ypfx/721/721_combine_in_practice.pdf?dl=1[PDF of presentation notes]
 
-A number of additional sessions mention Combine:
+A number of additional WWDC19 sessions mention Combine:
 
 * https://developer.apple.com/videos/play/wwdc2019/415/[Modern Swift API Design]
 * https://developer.apple.com/videos/play/wwdc2019/226[Data Flow Through SwiftUI]

docs/using-combine-book.adoc

@@ -23,7 +23,6 @@ v0.1, 2019-06-23
 ifndef::ebook-format[:leveloffset: 1]
 
 include::aboutthisbook.adoc[]
-
 include::introduction.adoc[]
 include::coreconcepts.adoc[]
 include::patterns.adoc[]