adding abstracts and organization to methods

Author: heckj

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(_:)-(Service)``
+
+### Running a service group
+
+- ``run(file:line:)``
+- ``run()``
+- ``triggerGracefulShutdown()``

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

@@ -47,7 +47,7 @@ public actor ServiceGroup: Sendable, Service {
     /// The current state of the group.
     private var state: State
 
-    /// Initializes a new ``ServiceGroup``.
+    /// Initializes 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``.
+    /// Initializes a service group.
     ///
     /// - Parameters:
     ///   - services: The groups's service configurations.
@@ -91,6 +91,9 @@ public actor ServiceGroup: Sendable, Service {
         self.init(configuration: configuration)
     }
 
+    /// Initializes a service group.
+    ///
+    /// Use ``init(services:gracefulShutdownSignals:cancellationSignals:logger:)`` instead.
     @available(*, deprecated, renamed: "init(services:gracefulShutdownSignals:cancellationSignals:logger:)")
     public init(
         services: [any Service],