Update Documentation (#13)

* chore: cleanup packages.swift file

* test: remove always failing tests due to .plist restrictions since xcode13

* docs: remove typos and enhance readability of documentation

Package.swift

@@ -6,23 +6,17 @@ import PackageDescription
 let package = Package(
     name: "SwiftVersionCompare",
     products: [
-        // Products define the executables and libraries a package produces, and make them visible to other packages.
         .library(
             name: "SwiftVersionCompare",
             targets: ["SwiftVersionCompare"]),
     ],
-    dependencies: [
-        // Dependencies declare other packages that this package depends on.
-        // .package(url: /* package url */, from: "1.0.0"),
-    ],
     targets: [
-        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
-        // Targets can depend on other targets in this package, and on products in packages this package depends on.
         .target(
             name: "SwiftVersionCompare",
             dependencies: []),
         .testTarget(
             name: "SwiftVersionCompareTests",
-            dependencies: ["SwiftVersionCompare"]),
+            dependencies: ["SwiftVersionCompare"]
+        ),
     ]
 )

Sources/SwiftVersionCompare/SemanticVersionComparable/PrereleaseIdentifier/PrereleaseIdentifier.swift

@@ -5,7 +5,7 @@
 //  Created by Marius Felkner on 12.03.21.
 //
 
-/// Enumerated pre-release identifier for `SemVer` conform initializing and handling.
+/// Enumerated pre-release identifier for `SemVer`.
 ///
 /// - Note: Identifier can be described using alphanumeric or numeric letters.
 ///

Sources/SwiftVersionCompare/SemanticVersionComparable/SemanticVersionComparable.swift

@@ -5,26 +5,26 @@
 //  Created by Marius Felkner on 29.12.20.
 //
 
-/// A type that can be expressed as a semantic version conforming to `SemVer`.
+/// A type that can be expressed and utilized as a semantic version conforming to `SemVer`.
 ///
-/// Additionally to the ranking rules, when comparing two versions, if their version core identifiers are `nil` they
+/// Additionally to the ranking and comparison rules if their version core identifiers are `nil` they
 /// will be treated as `0`.
 ///
 ///     let versionOne = Version(1, 0, 0)
 ///     let versionTwo = Version(1)
 ///
 ///     versionOne == versionTwo // <- this statement is `true`
 ///
-/// You can choose between a loosly or strictly comparison considering if you want to compare the build-meta-data of
-/// the version
+/// You can choose between a loosly or strictly comparison considering if you want to include the build-meta-data of
+/// versions when comparing:
 ///
 ///     let versionOne = Version(1, 0, 0, [.alpha])
 ///     let versionTwo = Version(1, 0, 0, [.alpha], ["exp"])
 ///
 ///     versionOne == versionTwo // `true`
 ///     versionOne === versionTwo // `false`
 ///
-/// - Remark: See `https://semver.org` for detailed information.
+/// - Remark: See [semver.org](https://semver.org) for detailed information.
 public protocol SemanticVersionComparable: Comparable, Hashable {
     /// The `MAJOR` identifier of a version.
     var major: UInt { get }
@@ -45,20 +45,20 @@ public extension SemanticVersionComparable {
     /// A boolean value indicating the compatibility of two versions. As `SemVer` states two versions are
     /// compatible if they have the same major version.
     ///
-    /// - Parameter version: An version object that conforms to the `SemanticVersionComparable`protocol.
+    /// - Parameter version: A version object that conforms to the `SemanticVersionComparable` protocol.
     ///
-    /// - Returns: `true` if both objects have equal major versions.
+    /// - Returns: `true` if both versions have equal major versions.
     func isCompatible(with version: Self) -> Bool {
         major == version.major
     }
 
-    /// Compare a version object (lhs) with a greater version object (rhs). Lhs must be a lower version to return
-    /// a valid result otherwise `.noUpdate` will be returned regardless of the difference between the two version
-    /// objects.
+    /// Compare a object (lhs) conforming to `SemanticVersionComparable` with a greater version object (rhs).
+    /// Lhs must be a lower version to return a valid result. Otherwise `.noUpdate` will be
+    /// returned regardless of the difference between the two version objects.
     ///
-    /// - Parameter version: The version you want to compare to another version.
+    /// - Parameter version: A version object that conforms to the `SemanticVersionComparable` protocol that will be compared.
     ///
-    /// - Returns: The severity of the update the version inherits.
+    /// - Returns: A `VersionCompareResult` as the severity of the update.
     func compare(with version: Self) -> VersionCompareResult {
         let lhs = self
         let rhs = version
@@ -94,7 +94,7 @@ public extension SemanticVersionComparable {
 
     /// Check if a version has an equal version core as another version.
     ///
-    /// - Parameter version: The other version you want to check with.
+    /// - Parameter version: A version object that conforms to the `SemanticVersionComparable` protocol.
     ///
     /// - Returns: `true` if the respective version cores are equal.
     ///

Sources/SwiftVersionCompare/Version.swift

@@ -5,10 +5,10 @@
 //  Created by Marius Felkner on 29.12.20.
 //
 
-/// A version type conforming to `SemVer`.
+/// A version type conforming to `SemanticVersionComparable` and therefor `SemVer`.
 ///
-/// You can create a new version using string, string literals and string interpolation formatted
-/// like `MAJOR.MINOR.PATCH-PRERELEASE+BUILD` or memberwise properties.
+/// You can create a new version using strings, string literals and string interpolations, formatted
+/// like `MAJOR.MINOR.PATCH-PRERELEASE+BUILD`, or memberwise initialization.
 ///
 ///     // from string
 ///     let version: Version? = "1.0.0"
@@ -21,8 +21,8 @@
 ///     let version: Version = Version(1, 0, 0)
 ///     let version: Version = Version(major: 1, minor: 0, patch: 0, prerelease: ["alpha, "1"], build: ["exp"])
 ///
-/// Pre-release identifier or build-meta-data can be handled as strings or as a few selected enumared case with it
-/// associated raw value (see `PrereleaseIdentifier` and `BuildMetaData` for more).
+/// Pre-release identifiers or build-meta-data can be handled as strings or as enum cases with it associated raw
+/// values (see `PrereleaseIdentifier` and `BuildMetaData` for more).
 ///
 ///     let version: Version = Version(major: 1, minor: 0, patch: 0, prerelease: ["alpha"], build: ["500"])
 ///     version.absoluteString // -> "1.0.0-alpha+500"
@@ -34,7 +34,7 @@
 ///     version.prereleaseIdentifer // -> "family.alpha"
 ///     version.buildMetaDataString // -> "1"
 ///
-/// - Remark: See `https://semver.org` for detailed information.
+/// - Remark: See [semver.org](https://semver.org) for detailed information.
 public struct Version: SemanticVersionComparable {
     public var major: UInt
     public var minor: UInt?

Tests/SwiftVersionCompareTests/VersionTests.swift

@@ -164,17 +164,17 @@ final class VersionTests: XCTestCase {
         }
     }
 
-    func testInvalidBundleVersion() {
-        // the main bundle from test targets is different from actual app targets and will be invalid for use,
-        // but not for testing
-        XCTAssertNil(Bundle.main.shortVersion)
-        XCTAssertNil(Bundle.main.version)
-    }
-
     // FIXME: Since the pipeline will use `swift test` resulting in different bundles that were previously
     //        expected here this test will always fail. A new way to access a .plist file during a test
     //        which contains the required keys is necessary to pass the test. It is not a critcal functionality
     //        using a direct first party API therefor this test is disabled unless fixed.
+//    func testInvalidBundleVersion() {
+//        // the main bundle from test targets is different from actual app targets and will be invalid for use,
+//        // but not for testing
+//        XCTAssertNil(Bundle.main.shortVersion)
+//        XCTAssertNil(Bundle.main.version)
+//    }
+
 //    func testValidBundleVersion() {
 //        let testBundle = Bundle(for: type(of: self))
 //        let shortVersionString = testBundle.infoDictionary?["CFBundleShortVersionString"] as? String