adding curation and updates to configuration types

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/ServiceGroupConfiguration.md

@@ -0,0 +1,32 @@
+# ``ServiceLifecycle/ServiceGroupConfiguration``
+
+## Topics
+
+### Creating a service group configuration
+
+- ``init(services:logger:)-([Service],_)``
+- ``init(services:logger:)-([ServiceConfiguration],_)``
+- ``init(gracefulShutdownSignals:)``
+
+### Creating a new service group configuration with signal handlers
+
+- ``init(services:gracefulShutdownSignals:cancellationSignals:logger:)-([Service],_,_,_)``
+- ``init(services:gracefulShutdownSignals:cancellationSignals:logger:)-([ServiceConfiguration],_,_,_)``
+
+### 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/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 service group.
+    /// 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 service group.
+    /// Creates a service group.
     ///
     /// - Parameters:
     ///   - services: The groups's service configurations.
@@ -91,7 +91,7 @@ public actor ServiceGroup: Sendable, Service {
         self.init(configuration: configuration)
     }
 
-    /// Initializes a service group.
+    /// Creates a service group.
     ///
     /// Use ``init(services:gracefulShutdownSignals:cancellationSignals:logger:)`` instead.
     @available(*, deprecated, renamed: "init(services:gracefulShutdownSignals:cancellationSignals:logger:)")
@@ -112,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.
@@ -134,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.
@@ -155,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
@@ -57,11 +62,15 @@ 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 = []