Improve documentation

Sources/Layout/Layout.swift

@@ -17,14 +17,14 @@ import UIKit
  * conformance to `LayoutItem` is provided automatically. A view can have multiple `Layout` instances as needed.
  * A subview can exist in multiple `Layout` instances to, for example, represent exclusively-activated distinct states.
  *
- * For example, the following code creates a layout with a single item.
+ * The following code shows how to create and activate a layout with a single item:
  *
  * ```swift
  * view.layout(subview.toEdges()).activate()
  * ```
  *
- * The following code demonstrates the preferred way of creating a layout with multiple items using result
- * builder syntax.
+ * The following code demonstrates the preferred way of constructing and activating a layout with multiple items
+ * using result builder syntax:
  *
  * ```swift
  * view.layout {
@@ -37,6 +37,9 @@ import UIKit
  * .activate()
  * ```
  *
+ * - Note: A ``LayoutItem`` extension is provided that defines the declarative methods used to create constraints for
+ *   the subviews within a layout.
+ *
  * - Important: The ``Layout/activate()`` method must be called to activate the constraints of the layout.
  *   Calling ``Layout/deactivate()`` does not hide or remove subviews.
  */
@@ -443,9 +446,7 @@ public final class Layout { // swiftlint:disable:this type_body_length
     /// Adds constraints horizontally centering the given view between two anchors.
     ///
     /// The center of the view is horizontally aligned to the center of a layout guide where the leading and trailing
-    /// edges of the layout guide are aligned to the given anchors.
-    ///
-    /// Example:
+    /// edges of the layout guide are aligned to the given anchors, as the following code demonstrates:
     ///
     /// ```swift
     /// view.layout {
@@ -503,9 +504,7 @@ public final class Layout { // swiftlint:disable:this type_body_length
     /// Adds constraints vertically centering the given view between two anchors.
     ///
     /// The center of the view is vertically aligned to the center of a layout guide where the top and bottom edges
-    /// of the layout guide are aligned to the given anchors.
-    ///
-    /// Example:
+    /// of the layout guide are aligned to the given anchors, as the following code demonstrates:
     ///
     /// ```swift
     /// view.layout {

Sources/Layout/LayoutItem.swift

@@ -17,15 +17,10 @@ import UIKit
 public typealias SuperviewConstraints = (LayoutItem) -> [NSLayoutConstraint]
 
 /**
- * Each subview and its constraints are stored as a `LayoutItem` instance within a ``Layout``.
+ * Each subview and its constraints are stored as a `LayoutItem` instance within a ``Layout``. A `LayoutItem` extension
+ * is provided that defines the declarative methods used to create constraints for the subviews within a layout.
  *
- * A `LayoutItem` extension is provided that defines the declarative methods used to create
- * [`NSLayoutConstraint`](https://developer.apple.com/documentation/uikit/nslayoutconstraint) instances for a `Layout`.
- *
- * - Important: [`UIView`](https://developer.apple.com/documentation/uikit/uiview) conformance to `LayoutItem` is
- *   provided automatically.
- *
- * A layout item must be added to a `Layout` in order to activate its constraints, for example:
+ * A layout item must be added to a `Layout` in order to activate its constraints, as the following code demonstrates:
  *
  * ```swift
  * // Creating a layout with a single item
@@ -38,8 +33,8 @@ public typealias SuperviewConstraints = (LayoutItem) -> [NSLayoutConstraint]
  * view.layout().addItems(item1, item2).activate()
  * ```
  *
- * The following code demonstrates the preferred way of creating a layout with multiple items using result
- * builder syntax.
+ * The following code demonstrates the preferred way of constructing and activating a layout with multiple items
+ * using result builder syntax:
  *
  * ```swift
  * view.layout {
@@ -51,6 +46,9 @@ public typealias SuperviewConstraints = (LayoutItem) -> [NSLayoutConstraint]
  * }
  * .activate()
  * ```
+ *
+ * - Important: [`UIView`](https://developer.apple.com/documentation/uikit/uiview) conformance to `LayoutItem` is
+ *   provided automatically.
  */
 @preconcurrency
 @MainActor
@@ -299,9 +297,7 @@ extension LayoutItem {
     /// Adds constraints horizontally centering the ``layoutItemView`` between the given anchors.
     ///
     /// The center of the view is horizontally aligned to the center of a layout guide where the leading and trailing
-    /// edges of the layout guide are aligned to the given anchors.
-    ///
-    /// Example:
+    /// edges of the layout guide are aligned to the given anchors, as the following code demonstrates:
     ///
     /// ```swift
     /// view.layout {
@@ -357,9 +353,7 @@ extension LayoutItem {
     /// Adds constraints vertically centering the ``layoutItemView`` between the given anchors.
     ///
     /// The center of the view is vertically aligned to the center of a layout guide where the top and bottom edges of
-    /// the layout guide are aligned to the given anchors.
-    ///
-    /// Example:
+    /// the layout guide are aligned to the given anchors, as the following code demonstrates:
     ///
     /// ```swift
     /// view.layout {

Sources/Layout/UIKit/UIView+Layout.swift

@@ -44,7 +44,7 @@ extension UIView {
     /// A subview can exist in multiple `Layout` instances to, for example, represent exclusively-activated
     /// distinct states.
     ///
-    /// Example:
+    /// The following code shows how to create and activate a layout with a single item:
     ///
     /// ```swift
     /// view.layout(subview.toEdges()).activate()
@@ -78,7 +78,8 @@ extension UIView {
     /// A subview can exist in multiple `Layout` instances to, for example, represent exclusively-activated
     /// distinct states.
     ///
-    /// Example:
+    /// The following code demonstrates the preferred way of constructing and activating a layout with multiple items
+    /// using result builder syntax:
     ///
     /// ```swift
     /// view.layout {

Sources/Layout/_Documentation.docc/Layout.md

@@ -25,3 +25,5 @@ override func viewDidLoad() {
     .activate()
 }
 ```
+
+Methods for creating constraints exist on the ``Layout`` instance as well as the individual ``LayoutItem`` instances.