Merge pull request #252 from lorentey/add-documentation-bundles

[1.0] Add DocC documentation bundles

.gitignore

@@ -7,3 +7,4 @@ xcuserdata/
 .*.sw?
 /Benchmarks/.swiftpm
 /Benchmarks/.build
+.docc-build

.spi.yml

@@ -0,0 +1,4 @@
+version: 1
+builder:
+  configs:
+    - documentation_targets: [Collections, DequeModule, OrderedCollections]

Package.swift

@@ -63,7 +63,7 @@ let package = Package(
         "OrderedCollections",
       ],
       path: "Sources/Collections",
-      exclude: ["CMakeLists.txt"],
+      exclude: ["CMakeLists.txt", "Collections.docc"],
       swiftSettings: settings),
 
     // Testing support module
@@ -85,7 +85,7 @@ let package = Package(
     // Deque<Element>
     .target(
       name: "DequeModule",
-      exclude: ["CMakeLists.txt"],
+      exclude: ["CMakeLists.txt", "DequeModule.docc"],
       swiftSettings: settings),
     .testTarget(
       name: "DequeTests",
@@ -95,7 +95,7 @@ let package = Package(
     // OrderedSet<Element>, OrderedDictionary<Key, Value>
     .target(
       name: "OrderedCollections",
-      exclude: ["CMakeLists.txt"],
+      exclude: ["CMakeLists.txt", "OrderedCollections.docc"],
       swiftSettings: settings),
     .testTarget(
       name: "OrderedCollectionsTests",

Package@swift-5.5.swift

@@ -0,0 +1,100 @@
+// swift-tools-version:5.5
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Collections open source project
+//
+// Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+// This package recognizes the conditional compilation flags listed below.
+// To use enable them, uncomment the corresponding lines or define them
+// from the package manager command line:
+//
+//     swift build -Xswiftc -DCOLLECTIONS_INTERNAL_CHECKS
+var settings: [SwiftSetting] = [
+
+  // Enables internal consistency checks at the end of initializers and
+  // mutating operations. This can have very significant overhead, so enabling
+  // this setting invalidates all documented performance guarantees.
+  //
+  // This is mostly useful while debugging an issue with the implementation of
+  // the hash table itself. This setting should never be enabled in production
+  // code.
+//  .define("COLLECTIONS_INTERNAL_CHECKS"),
+
+  // Hashing collections provided by this package usually seed their hash
+  // function with the address of the memory location of their storage,
+  // to prevent some common hash table merge/copy operations from regressing to
+  // quadratic behavior. This setting turns off this mechanism, seeding
+  // the hash function with the table's size instead.
+  //
+  // When used in conjunction with the SWIFT_DETERMINISTIC_HASHING environment
+  // variable, this enables reproducible hashing behavior.
+  //
+  // This is mostly useful while debugging an issue with the implementation of
+  // the hash table itself. This setting should never be enabled in production
+  // code.
+//  .define("COLLECTIONS_DETERMINISTIC_HASHING"),
+]
+
+let package = Package(
+  name: "swift-collections",
+  products: [
+    .library(name: "Collections", targets: ["Collections"]),
+    .library(name: "DequeModule", targets: ["DequeModule"]),
+    .library(name: "OrderedCollections", targets: ["OrderedCollections"]),
+  ],
+  targets: [
+    .target(
+      name: "Collections",
+      dependencies: [
+        "DequeModule",
+        "OrderedCollections",
+      ],
+      path: "Sources/Collections",
+      exclude: ["CMakeLists.txt"],
+      swiftSettings: settings),
+
+    // Testing support module
+    .target(
+      name: "_CollectionsTestSupport",
+      dependencies: [],
+      swiftSettings: settings,
+      linkerSettings: [
+        .linkedFramework(
+          "XCTest",
+          .when(platforms: [.macOS, .iOS, .watchOS, .tvOS])),
+      ]
+    ),
+    .testTarget(
+      name: "CollectionsTestSupportTests",
+      dependencies: ["_CollectionsTestSupport"],
+      swiftSettings: settings),
+
+    // Deque<Element>
+    .target(
+      name: "DequeModule",
+      exclude: ["CMakeLists.txt"],
+      swiftSettings: settings),
+    .testTarget(
+      name: "DequeTests",
+      dependencies: ["DequeModule", "_CollectionsTestSupport"],
+      swiftSettings: settings),
+
+    // OrderedSet<Element>, OrderedDictionary<Key, Value>
+    .target(
+      name: "OrderedCollections",
+      exclude: ["CMakeLists.txt"],
+      swiftSettings: settings),
+    .testTarget(
+      name: "OrderedCollectionsTests",
+      dependencies: ["OrderedCollections", "_CollectionsTestSupport"],
+      swiftSettings: settings),
+  ]
+)

Sources/Collections/Collections.docc/Collections.md

@@ -0,0 +1,47 @@
+# ``Collections``
+
+**Swift Collections** is an open-source package of data structure implementations for the Swift programming language.
+
+The package currently provides the following implementations:
+
+- ``Deque``, a double-ended queue backed by a ring buffer. Deques are range-replaceable, mutable, random-access collections.
+
+- ``OrderedSet``, a variant of the standard `Set` where the order of items is well-defined and items can be arbitrarily reordered. Uses a `ContiguousArray` as its backing store, augmented by a separate hash table of bit packed offsets into it.
+
+- ``OrderedDictionary``, an ordered variant of the standard `Dictionary`, providing similar benefits.
+
+## Modules
+
+This package provides separate products for each group of data structures it implements:
+
+- ``Collections``. This is an umbrella module that exports every other public module in the package.
+- ``DequeModule``. Defines ``Deque``.
+- ``OrderedCollections``. Defines the ordered collection types ``OrderedSet`` and ``OrderedDictionary``.
+
+If you aren't constrained by code size limitations, then importing ``Collections`` is the simplest way to start using the package.
+
+```swift
+import Collections
+
+var deque: Deque = ["Ted", "Rebecca"]
+deque.prepend("Keeley")
+
+let people = OrderedSet(deque)
+people.contains("Rebecca") // true
+```
+
+#### Additional Resources
+
+- [`Swift Collections` on GitHub](https://github.com/apple/swift-collections/)
+- [`Swift Collections` on the Swift Forums](https://forums.swift.org/c/related-projects/collections/72)
+
+## Topics
+
+### Deque Module
+
+- ``Deque``
+
+### Ordered Collections
+
+- ``OrderedSet``
+- ``OrderedDictionary``

Sources/Collections/Collections.docc/Extensions/Deque.md

@@ -0,0 +1,67 @@
+# ``Collections/Deque``
+
+<!-- DO NOT EDIT THIS FILE; IT'S AUTOMATICALLY GENERATED -->
+
+
+## Topics
+
+### Creating a Deque
+
+- ``init()``
+- ``init(_:)-8tyaw``
+- ``init(_:)-1tqf4``
+- ``init(minimumCapacity:)``
+- ``init(repeating:count:)-4v1gt``
+- ``init(unsafeUninitializedCapacity:initializingWith:)``
+
+### Inspecting a Deque
+
+- ``count-8wcnm``
+- ``isEmpty``
+
+### Manipulating Elements at the Front
+
+- ``first``
+- ``prepend(_:)``
+- ``prepend(contentsOf:)-96y15``
+- ``prepend(contentsOf:)-51zn6``
+- ``removeFirst()-1vdmt``
+- ``removeFirst(_:)-2vuji``
+- ``popFirst()``
+- ``prefix(_:)``
+
+### Manipulating Elements at the End
+
+- ``last``
+- ``append(_:)-9h4m7``
+- ``append(contentsOf:)-8rqnl``
+- ``append(contentsOf:)-29aoh``
+- ``removeLast()``
+- ``removeLast(_:)``
+- ``popLast()``
+- ``suffix(_:)``
+
+### Manipulating Elements Elsewhere
+
+- ``subscript(_:)-9nk44``
+- ``subscript(_:)-6ee8i``
+- ``subscript(_:)-1klky``
+- ``subscript(_:)-ejld``
+- ``insert(_:at:)-9hsp7``
+- ``insert(contentsOf:at:)-1d60f``
+- ``replaceSubrange(_:with:)-5rtzd``
+- ``remove(at:)-3imgi``
+
+### Reordering Elements
+
+- ``swapAt(_:_:)-7910s``
+- ``sort()``
+- ``sort(by:)``
+- ``reverse()``
+- ``shuffle()``
+- ``shuffle(using:)``
+- ``partition(by:)-90y0t``
+
+### Memory Management
+
+- ``reserveCapacity(_:)``

Sources/Collections/Collections.docc/Extensions/OrderedDictionary.Elements.md

@@ -0,0 +1,40 @@
+# ``Collections/OrderedDictionary/Elements-swift.struct``
+
+<!-- DO NOT EDIT THIS FILE; IT'S AUTOMATICALLY GENERATED -->
+
+
+## Topics
+
+### Inspecting an Elements View
+
+- ``isEmpty``
+- ``count``
+
+### Accessing Elements
+
+- ``subscript(_:)-4xwc2``
+- ``keys``
+- ``values``
+- ``index(forKey:)``
+
+### Removing Elements
+
+- ``remove(at:)``
+- ``removeSubrange(_:)-5x7oo``
+- ``removeSubrange(_:)-7wdak``
+- ``removeAll(keepingCapacity:)``
+- ``removeAll(where:)``
+- ``removeFirst()``
+- ``removeFirst(_:)``
+- ``removeLast()``
+- ``removeLast(_:)``
+
+### Reordering Elements
+
+- ``swapAt(_:_:)``
+- ``reverse()``
+- ``sort()``
+- ``sort(by:)``
+- ``partition(by:)``
+- ``shuffle()``
+- ``shuffle(using:)``

Sources/Collections/Collections.docc/Extensions/OrderedDictionary.Values.md

@@ -0,0 +1,27 @@
+# ``Collections/OrderedDictionary/Values-swift.struct``
+
+<!-- DO NOT EDIT THIS FILE; IT'S AUTOMATICALLY GENERATED -->
+
+
+## Topics
+
+### Inspecting a Values Collection
+
+- ``isEmpty``
+- ``count``
+
+### Accessing Elements
+
+- ``subscript(_:)-25vfz``
+- ``elements``
+- ``withUnsafeBufferPointer(_:)``
+- ``withUnsafeMutableBufferPointer(_:)``
+
+### Reordering Elements
+
+- ``swapAt(_:_:)-77eiy``
+- ``partition(by:)-9x0i5``
+- ``sort()``
+- ``sort(by:)``
+- ``shuffle()``
+- ``shuffle(using:)``