adding abstracts and organization to methods (#205)

A little bit of docs cleanup - adding abstracts for deprecated methods
and curating them (organizing them) to the bottom of the relevant lists.

Author: heckj

Sources/ServiceLifecycle/Docs.docc/LoggingConfiguration.md

@@ -0,0 +1,12 @@
+# ``ServiceLifecycle/ServiceGroupConfiguration/LoggingConfiguration``
+
+## Topics
+
+### Creating a logging configuration
+
+- ``init()``
+
+### Inspecting a service group configuration
+
+- ``keys``
+- ``Keys-swift.struct``

Sources/ServiceLifecycle/Docs.docc/ServiceConfiguration.md

@@ -0,0 +1,14 @@
+# ``ServiceLifecycle/ServiceGroupConfiguration/ServiceConfiguration``
+
+## Topics
+
+### Creating a service configuration
+
+- ``init(service:successTerminationBehavior:failureTerminationBehavior:)``
+
+### Inspecting a service configuration
+
+- ``service``
+- ``failureTerminationBehavior``
+- ``successTerminationBehavior``
+- ``TerminationBehavior``

Sources/ServiceLifecycle/Docs.docc/ServiceGroup.md

@@ -0,0 +1,20 @@
+# ``ServiceLifecycle/ServiceGroup``
+
+## Topics
+
+### Creating a service group
+
+- ``init(configuration:)``
+- ``init(services:gracefulShutdownSignals:cancellationSignals:logger:)``
+- ``init(services:configuration:logger:)``
+
+### Adding to a service group
+
+- ``addServiceUnlessShutdown(_:)-r47h``
+- ``addServiceUnlessShutdown(_:)-9jpoj``
+
+### Running a service group
+
+- ``run(file:line:)``
+- ``run()``
+- ``triggerGracefulShutdown()``

Sources/ServiceLifecycle/Docs.docc/ServiceGroupConfiguration.md

@@ -0,0 +1,32 @@
+# ``ServiceLifecycle/ServiceGroupConfiguration``
+
+## Topics
+
+### Creating a service group configuration
+
+- ``init(services:logger:)-309oa``
+- ``init(services:logger:)-2mhze``
+- ``init(gracefulShutdownSignals:)``
+
+### Creating a new service group configuration with signal handlers
+
+- ``init(services:gracefulShutdownSignals:cancellationSignals:logger:)-9uhzu``
+- ``init(services:gracefulShutdownSignals:cancellationSignals:logger:)-1noxs``
+
+### Inspecting the service group services
+
+- ``services``
+- ``ServiceConfiguration``
+
+### Inspecting the service group logging
+
+- ``logging``
+- ``LoggingConfiguration``
+- ``logger``
+
+### Inspecting the service group signal handling
+
+- ``cancellationSignals``
+- ``maximumCancellationDuration``
+- ``gracefulShutdownSignals``
+- ``maximumGracefulShutdownDuration``

Sources/ServiceLifecycle/Docs.docc/index.md

@@ -76,12 +76,17 @@ let package = Package(
 
 - ``ServiceGroup``
 - ``ServiceGroupConfiguration``
+- ``ServiceGroupError``
 
 ### Graceful Shutdown
 
-- ``withGracefulShutdownHandler(operation:onGracefulShutdown:)``
-- ``cancelOnGracefulShutdown(_:)``
-
-### Errors
+- ``gracefulShutdown()``
+- ``cancelWhenGracefulShutdown(_:)``
+- ``withTaskCancellationOrGracefulShutdownHandler(isolation:operation:onCancelOrGracefulShutdown:)``
+- ``withGracefulShutdownHandler(isolation:operation:onGracefulShutdown:)``
+- ``AsyncCancelOnGracefulShutdownSequence``
 
-- ``ServiceGroupError``
+- ``cancelOnGracefulShutdown(_:)``
+- ``withGracefulShutdownHandler(operation:onGracefulShutdown:)``
+- ``withGracefulShutdownHandler(operation:onGracefulShutdown:)-1x21p``
+- ``withTaskCancellationOrGracefulShutdownHandler(operation:onCancelOrGracefulShutdown:)-81m01``

Sources/ServiceLifecycle/GracefulShutdown.swift

@@ -58,6 +58,9 @@ public func withGracefulShutdownHandler<T>(
     return try await operation()
 }
 
+/// Execute an operation with a graceful shutdown handler that’s immediately invoked if the current task is shutting down gracefully.
+///
+/// Use ``withGracefulShutdownHandler(isolation:operation:onGracefulShutdown:)`` instead.
 @available(*, deprecated, message: "Use the method with the isolation parameter instead.")
 @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
 @_disfavoredOverload
@@ -142,6 +145,11 @@ public func withTaskCancellationOrGracefulShutdownHandler<T>(
         handler()
     }
 }
+
+/// Execute an operation with a graceful shutdown or task cancellation handler that’s immediately invoked if the current task is
+/// shutting down gracefully or has been cancelled.
+///
+/// Use ``withTaskCancellationOrGracefulShutdownHandler(isolation:operation:onCancelOrGracefulShutdown:)`` instead.
 @available(*, deprecated, message: "Use the method with the isolation parameter instead.")
 @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
 @_disfavoredOverload
@@ -156,6 +164,10 @@ public func withTaskCancellationOrGracefulShutdownHandler<T>(
     }
 }
 #else
+/// Execute an operation with a graceful shutdown or task cancellation handler that’s immediately invoked if the current task is
+/// shutting down gracefully or has been cancelled.
+///
+/// Use ``withTaskCancellationOrGracefulShutdownHandler(isolation:operation:onCancelOrGracefulShutdown:)`` instead.
 @available(*, deprecated, message: "Use the method with the isolation parameter instead.")
 @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
 @_disfavoredOverload
@@ -244,6 +256,7 @@ public func cancelWhenGracefulShutdown<T: Sendable>(
 
 /// Cancels the closure when a graceful shutdown was triggered.
 ///
+/// Use ``cancelWhenGracefulShutdown(_:)`` instead.
 /// - Parameter operation: The actual operation.
 #if compiler(>=6.0)
 @available(*, deprecated, renamed: "cancelWhenGracefulShutdown")

Sources/ServiceLifecycle/ServiceGroup.swift

@@ -16,7 +16,7 @@ import Logging
 import UnixSignals
 import AsyncAlgorithms
 
-/// A ``ServiceGroup`` is responsible for running a number of services, setting up signal handling and signalling graceful shutdown to the services.
+/// A service group is responsible for running a number of services, setting up signal handling and signalling graceful shutdown to the services.
 @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
 public actor ServiceGroup: Sendable, Service {
     /// The internal state of the ``ServiceGroup``.
@@ -47,7 +47,7 @@ public actor ServiceGroup: Sendable, Service {
     /// The current state of the group.
     private var state: State
 
-    /// Initializes a new ``ServiceGroup``.
+    /// Creates a service group.
     ///
     /// - Parameters:
     ///   - configuration: The group's configuration
@@ -68,7 +68,7 @@ public actor ServiceGroup: Sendable, Service {
         self.maximumCancellationDuration = configuration._maximumCancellationDuration
     }
 
-    /// Initializes a new ``ServiceGroup``.
+    /// Creates a service group.
     ///
     /// - Parameters:
     ///   - services: The groups's service configurations.
@@ -91,6 +91,9 @@ public actor ServiceGroup: Sendable, Service {
         self.init(configuration: configuration)
     }
 
+    /// Creates a service group.
+    ///
+    /// Use ``init(services:gracefulShutdownSignals:cancellationSignals:logger:)`` instead.
     @available(*, deprecated, renamed: "init(services:gracefulShutdownSignals:cancellationSignals:logger:)")
     public init(
         services: [any Service],
@@ -109,7 +112,7 @@ public actor ServiceGroup: Sendable, Service {
         self.maximumCancellationDuration = configuration._maximumCancellationDuration
     }
 
-    /// Adds a new service to the group.
+    /// Adds a service to the group.
     ///
     /// If the group is currently running, the added service will be started immediately.
     /// If the group is gracefully shutting down, cancelling, or already finished, the added service will not be started.
@@ -131,7 +134,7 @@ public actor ServiceGroup: Sendable, Service {
         }
     }
 
-    /// Adds a new service to the group.
+    /// Adds a service to the group.
     ///
     /// If the group is currently running, the added service will be started immediately.
     /// If the group is gracefully shutting down, cancelling, or already finished, the added service will not be started.
@@ -152,8 +155,8 @@ public actor ServiceGroup: Sendable, Service {
     }
 
     /// Runs all the services by spinning up a child task per service.
-    /// Furthermore, this method sets up the correct signal handlers
-    /// for graceful shutdown.
+    ///
+    /// Furthermore, this method sets up the correct signal handlers for graceful shutdown.
     public func run(file: String = #file, line: Int = #line) async throws {
         switch self.state {
         case .initial(var services):

Sources/ServiceLifecycle/ServiceGroupConfiguration.swift

@@ -17,11 +17,12 @@ import UnixSignals
 
 let deprecatedLoggerLabel = "service-lifecycle-deprecated-method-logger"
 
-/// The configuration for the ``ServiceGroup``.
+/// The configuration for the service group.
 @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
 public struct ServiceGroupConfiguration: Sendable {
     /// The group's logging configuration.
     public struct LoggingConfiguration: Sendable {
+        /// The keys to use for logging
         public struct Keys: Sendable {
             /// The logging key used for logging the unix signal.
             public var signalKey = "sl-signal"
@@ -36,19 +37,23 @@ public struct ServiceGroupConfiguration: Sendable {
             /// The logging key used for logging an error.
             public var errorKey = "sl-error"
 
-            /// Initializes a new ``ServiceGroupConfiguration/LoggingConfiguration/Keys``.
+            /// Creates a new set of keys.
             public init() {}
         }
 
         /// The keys used for logging.
         public var keys = Keys()
 
-        /// Initializes a new ``ServiceGroupConfiguration/LoggingConfiguration``.
+        /// Creates a new logging configuration.
         public init() {}
     }
 
+    /// A service configuration.
     public struct ServiceConfiguration: Sendable {
-        /// The behavior to follow when the service finishes its ``Service/run()`` method via returning or throwing.
+
+        /// The behavior to follow when the service finishes running.
+        ///
+        /// This describes what the service lifecycle code does when a service's run method returns or throws.
         public struct TerminationBehavior: Sendable, CustomStringConvertible {
             internal enum _TerminationBehavior {
                 case cancelGroup
@@ -58,10 +63,14 @@ public struct ServiceGroupConfiguration: Sendable {
 
             internal let behavior: _TerminationBehavior
 
+            /// Cancel the service group.
             public static let cancelGroup = Self(behavior: .cancelGroup)
+            /// Gracefully shut down the service group.
             public static let gracefullyShutdownGroup = Self(behavior: .gracefullyShutdownGroup)
+            /// Ignore the completion of the service.
             public static let ignore = Self(behavior: .ignore)
 
+            /// A string representation of the behavior when a service finishes running.
             public var description: String {
                 switch self.behavior {
                 case .cancelGroup:
@@ -76,17 +85,17 @@ public struct ServiceGroupConfiguration: Sendable {
 
         /// The service to which the initialized configuration applies.
         public var service: any Service
-        /// The behavior when the service returns from its ``Service/run()`` method.
+        /// The behavior when the service returns from its run method.
         public var successTerminationBehavior: TerminationBehavior
-        /// The behavior when the service throws from its ``Service/run()`` method.
+        /// The behavior when the service throws from its run method.
         public var failureTerminationBehavior: TerminationBehavior
 
-        /// Initializes a new ``ServiceGroupConfiguration/ServiceConfiguration``.
+        /// Initializes a new service configuration.
         ///
         /// - Parameters:
         ///   - service: The service to which the initialized configuration applies.
-        ///   - successTerminationBehavior: The behavior when the service returns from its ``Service/run()`` method.
-        ///   - failureTerminationBehavior: The behavior when the service throws from its ``Service/run()`` method.
+        ///   - successTerminationBehavior: The behavior when the service returns from its run method.
+        ///   - failureTerminationBehavior: The behavior when the service throws from its run method.
         public init(
             service: any Service,
             successTerminationBehavior: TerminationBehavior = .cancelGroup,
@@ -166,7 +175,7 @@ public struct ServiceGroupConfiguration: Sendable {
 
     internal var _maximumCancellationDuration: (secondsComponent: Int64, attosecondsComponent: Int64)?
 
-    /// Initializes a new ``ServiceGroupConfiguration``.
+    /// Creates a new service group configuration from the service configurations you provide.
     ///
     /// - Parameters:
     ///   - services: The groups's service configurations.
@@ -179,7 +188,7 @@ public struct ServiceGroupConfiguration: Sendable {
         self.logger = logger
     }
 
-    /// Initializes a new ``ServiceGroupConfiguration``.
+    /// Creates a new service group configuration from service configurations you provide with cancellation and shutdown signals.
     ///
     /// - Parameters:
     ///   - services: The groups's service configurations.
@@ -198,7 +207,7 @@ public struct ServiceGroupConfiguration: Sendable {
         self.cancellationSignals = cancellationSignals
     }
 
-    /// Initializes a new ``ServiceGroupConfiguration``.
+    /// Creates a new service group configuration from services you provide.
     ///
     /// - Parameters:
     ///   - services: The groups's services.
@@ -211,7 +220,7 @@ public struct ServiceGroupConfiguration: Sendable {
         self.logger = logger
     }
 
-    /// Initializes a new ``ServiceGroupConfiguration``.
+    /// Creates a new service group configuration from services you provide with cancellation and shutdown signals..
     ///
     /// - Parameters:
     ///   - services: The groups's services.
@@ -230,6 +239,7 @@ public struct ServiceGroupConfiguration: Sendable {
         self.cancellationSignals = cancellationSignals
     }
 
+    /// Initializes a new service group configuration.
     @available(*, deprecated)
     public init(gracefulShutdownSignals: [UnixSignal]) {
         self.services = []