extending abstracts for the docs, adding curation for more types

Author: heckj

Sources/ServiceLifecycle/AsyncCancelOnGracefulShutdownSequence.swift

@@ -24,7 +24,7 @@ extension AsyncSequence where Self: Sendable, Element: Sendable {
     }
 }
 
-/// An asynchronous sequence that is cancelled once graceful shutdown has triggered.
+/// An asynchronous sequence that is cancelled after graceful shutdown has triggered.
 @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
 public struct AsyncCancelOnGracefulShutdownSequence<Base: AsyncSequence & Sendable>: AsyncSequence, Sendable
 where Base.Element: Sendable {
@@ -40,24 +40,29 @@ where Base.Element: Sendable {
         AsyncMapSequence<AsyncMapNilSequence<AsyncGracefulShutdownSequence>, _ElementOrGracefulShutdown>
     >
 
+    /// The type that the sequence produces.
     public typealias Element = Base.Element
 
     @usableFromInline
     let _merge: Merged
 
+    /// Creates a new asynchronous sequence that cancels after graceful shutdown is triggered.
+    /// - Parameter base: The asynchronous sequence to wrap.
     @inlinable
     public init(base: Base) {
         self._merge = merge(
             base.mapNil().map { .base($0) },
             AsyncGracefulShutdownSequence().mapNil().map { _ in .gracefulShutdown }
         )
     }
-
+    
+    /// Creates an iterator for the sequence.
     @inlinable
     public func makeAsyncIterator() -> AsyncIterator {
         AsyncIterator(iterator: self._merge.makeAsyncIterator())
     }
-
+    
+    /// An iterator for an asynchronous sequence that cancels after graceful shutdown is triggered.
     public struct AsyncIterator: AsyncIteratorProtocol {
         @usableFromInline
         var _iterator: Merged.AsyncIterator
@@ -69,7 +74,8 @@ where Base.Element: Sendable {
         init(iterator: Merged.AsyncIterator) {
             self._iterator = iterator
         }
-
+        
+        /// Returns the next item in the sequence, or `nil` if the sequence is finished.
         @inlinable
         public mutating func next() async rethrows -> Element? {
             guard !self._isFinished else {

Sources/ServiceLifecycle/AsyncGracefulShutdownSequence.swift

@@ -14,7 +14,7 @@
 
 /// An async sequence that emits an element once graceful shutdown has been triggered.
 ///
-/// This sequence is a broadcast async sequence and will only produce one value and then finish.
+/// This sequence is a broadcast async sequence and only produces one value and then finishes.
 ///
 /// - Note: This sequence respects cancellation and thus is `throwing`.
 @usableFromInline

…dopt ServiceLifecycle in applications.md …ting ServiceLifecycle in applications.mdSources/ServiceLifecycle/Docs.docc/How to adopt ServiceLifecycle in applications.md renamed to Sources/ServiceLifecycle/Docs.docc/Adopting ServiceLifecycle in applications.md Sources/ServiceLifecycle/Docs.docc/How to adopt ServiceLifecycle in applications.md renamed to Sources/ServiceLifecycle/Docs.docc/Adopting ServiceLifecycle in applications.md

@@ -1,9 +1,9 @@
-# How to adopt ServiceLifecycle in applications
+# Adopting ServiceLifecycle in applications
 
 Service Lifecycle provides a unified API for services to streamline their
-orchestration in applications: the ServiceGroup actor.
+orchestration in applications: the Service Group actor.
 
-## Why do we need this?
+## Overview
 
 Applications often rely on fundamental observability services like logging and
 metrics, while long-running actors bundle the application's business logic in
@@ -13,24 +13,24 @@ orchestrate the various services during startup and shutdown.
 
 With the introduction of Structured Concurrency in Swift, multiple asynchronous
 services can be run concurrently with task groups. However, Structured
-Concurrency doesn't enforce consistent interfaces between the services, and it
-becomes hard to orchestrate them. To solve this issue, ``ServiceLifecycle``
+Concurrency doesn't enforce consistent interfaces between services, and it can
+become hard to orchestrate them. To solve this issue, ``ServiceLifecycle``
 provides the ``Service`` protocol to enforce a common API, as well as the
 ``ServiceGroup`` actor to orchestrate all services in an application.
 
 ## Adopting the ServiceGroup actor in your application
 
 This article focuses on how ``ServiceGroup`` works, and how you can adopt it in
 your application. If you are interested in how to properly implement a service,
-go check out the article: <doc:How-to-adopt-ServiceLifecycle-in-libraries>.
+go check out the article: <doc:Adopting-ServiceLifecycle-in-libraries>.
 
 ### How does the ServiceGroup actor work?
 
 Under the hood, the ``ServiceGroup`` actor is just a complicated task group that
 runs each service in a separate child task, and handles individual services
 exiting or throwing. It also introduces the concept of graceful shutdown, which
 allows the safe teardown of all services in reverse order. Graceful shutdown is
-often used in server scenarios, i.e., when rolling out a new version and
+often used in server scenarios, for example when rolling out a new version and
 draining traffic from the old version (commonly referred to as quiescing).
 
 ### How to use ServiceGroup?

…o adopt ServiceLifecycle in libraries.md …dopting ServiceLifecycle in libraries.mdSources/ServiceLifecycle/Docs.docc/How to adopt ServiceLifecycle in libraries.md renamed to Sources/ServiceLifecycle/Docs.docc/Adopting ServiceLifecycle in libraries.md Sources/ServiceLifecycle/Docs.docc/How to adopt ServiceLifecycle in libraries.md renamed to Sources/ServiceLifecycle/Docs.docc/Adopting ServiceLifecycle in libraries.md

@@ -1,22 +1,23 @@
-# How to adopt ServiceLifecycle in libraries
+# Adopting ServiceLifecycle in libraries
 
 Adopt the Service protocol for your service to allow a Service Group to coordinate it's operation with other services.
 
-Service Lifecycle provides a unified API to represent a long running task: the Service protocol.
+## Overview
 
-## Why do we need this?
+Service Lifecycle provides a unified API to represent a long running task: the ``Service`` protocol.
 
 Before diving into how to adopt this protocol in your library, let's take a step back and talk about why we need to have this unified API.
 Services often need to schedule long-running tasks, such as sending keep-alive pings in the background, or the handling of incoming work like new TCP connections.
 Before Swift Concurrency was introduced, services put their work into separate threads using a `DispatchQueue` or an NIO `EventLoop`.
 Services often required explicit lifetime management to make sure their resources, such as threads, were shut down correctly.
+
 With the introduction of Swift Concurrency, specifically by using Structured Concurrency, we have better tools to structure our programs and model our work as a tree of tasks.
-The ``Service`` protocol provides a common interface, a single `run()` method, for services to use when they run  their long-running work.
+The `Service` protocol provides a common interface, a single `run()` method, for services to use when they run  their long-running work.
 If all services in an application conform to this protocol, then orchestrating them becomes trivial.
 
 ## Adopting the Service protocol in your service
 
-Adopting the ``Service`` protocol is quite easy.
+Adopting the `Service` protocol is quite easy.
 The protocol's single requirement is the ``Service/run()`` method.
 Make sure that your service adheres to the important caveats addressed in the following sections.
 

Sources/ServiceLifecycle/Docs.docc/curation/AsyncCancelOnGracefulShutdownSequence.md

@@ -0,0 +1,13 @@
+# ``ServiceLifecycle/AsyncCancelOnGracefulShutdownSequence``
+
+## Topics
+
+### Creating a cancelling sequence
+
+- ``init(base:)``
+
+### Iterating the sequence
+
+- ``Element``
+- ``makeAsyncIterator()``
+- ``AsyncIterator``

…ecycle/Docs.docc/LoggingConfiguration.md …cs.docc/curation/LoggingConfiguration.mdSources/ServiceLifecycle/Docs.docc/LoggingConfiguration.md renamed to Sources/ServiceLifecycle/Docs.docc/curation/LoggingConfiguration.md Sources/ServiceLifecycle/Docs.docc/LoggingConfiguration.md renamed to Sources/ServiceLifecycle/Docs.docc/curation/LoggingConfiguration.md

@@ -0,0 +1,7 @@
+# ``ServiceLifecycle/Service``
+
+## Topics
+
+### Running a service
+
+- ``run()``