UI: add docs to AlertAction, AlertController

Add additional documentation for the members of these types.

Author: compnerd

Sources/SwiftWin32/Windows and Screens/AlertAction.swift

@@ -2,17 +2,25 @@
 // SPDX-License-Identifier: BSD-3-Clause
 
 extension AlertAction {
+  /// Styles to apply to action buttons in an alert.
   public enum Style: Int {
-  case `default`
-  case cancel
-  case destructive
+    /// Apply the default style to the action’s button.
+    case `default`
+
+    /// Apply a style that indicates the action cancels the operation and leaves
+    /// things unchanged.
+    case cancel
+
+    /// Apply a style that indicates the action might change or delete data.
+    case destructive
   }
 }
 
+/// An action that can be taken when the user taps a button in an alert.
 public class AlertAction {
   private let handler: ((AlertAction) -> Void)?
 
-  /// Creating an Alert Action
+  // MARK - Creating an Alert Action
 
   /// Create and return an action with the specified title and behavior.
   public init(title: String?, style: AlertAction.Style,
@@ -23,7 +31,7 @@ public class AlertAction {
     self.handler = handler
   }
 
-  /// Getting the Action's Attributes
+  // MARK - Getting the Action's Attributes
 
   /// The title of the action’s button.
   public let title: String?

Sources/SwiftWin32/Windows and Screens/AlertController.swift

@@ -4,25 +4,41 @@
 extension AlertController {
   /// Constants indicating the type of alert to display.
   public enum Style: Int {
+  /// An action sheet displayed in the context of the view controller that
+  /// presented it.
   case actionSheet
+
+  /// An alert displayed modally for the app.
   case alert
   }
 }
 
+/// An object that displays an alert message to the user.
 public class AlertController: ViewController {
-  /// Configuring the Alert
+  // MARK - Configuring the Alert
+
+  /// Descriptive text that provides more details about the reason for the
+  /// alert.
   public var message: String?
+
+  /// The style of the alert controller.
   public let preferredStyle: AlertController.Style
 
-  /// Creating an Alert Controller
+  // MARK - Creating an Alert Controller
+
+  /// Creates and returns a view controller for displaying an alert to the user.
   public init(title: String?, message: String?,
               preferredStyle: AlertController.Style) {
     self.message = message
     self.preferredStyle = preferredStyle
     super.init()
   }
 
-  /// Configuring the User Actions
+  // MARK - Configuring the User Actions
+
+  /// Attaches an action object to the alert or action sheet.
+  public func addAction(_ action: AlertAction) {
+  }
 
   /// The actions that the user can take in response to the alert or action
   /// sheet.
@@ -31,16 +47,12 @@ public class AlertController: ViewController {
   /// The preferred action for the user to take from an alert.
   public var preferredAction: AlertAction?
 
-  /// Attaches an action object to the alert or action sheet.
-  public func addAction(_ action: AlertAction) {
-  }
-
-  /// Configuring Text Fields
-
-  /// The array of text fields displayed by the alert.
-  public private(set) var textFields: [TextField]?
+  // MARK - Configuring Text Fields
 
   /// Adds a text field to an alert.
   public func addTextField(configurationHandler: ((TextField) -> Void)? = nil) {
   }
+
+  /// The array of text fields displayed by the alert.
+  public private(set) var textFields: [TextField]?
 }