Update Documentation (#12)

* docs: rename authors surname * refactor: rename error for usage clarity, add more detailed error description * refactor: append to last commit * docs: update documentation to most public methods for better understanding and usage * docs: minor text changes in readme * chore: add CHANGELOG.md
mflknr · Jul 22, 2021 · 060fa34 · 060fa34
1 parent 7390ea4
commit 060fa34
Show file tree

Hide file tree

Showing 24 changed files with 106 additions and 50 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,33 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.3] - 2021-07-22
+
+### Added
+
+- `CHANGELOG.md` for a better overview regarding all releases.
+- Localized error description to error type for more clarity.
+
+### Changed
+
+- Renamed `Error` to `VersionValidationError` for better understanding when parsing an invalid string.
+- Updated and enhanced documentation on public methods and properties.
+
+## [1.0.2] - 2021-03-30
+
+Fixed regex pattern for checking if string is alpha numeric or numeric. Removed minor typos and updated documentation.
+
+## [1.0.1] - 2021-03-30
+
+Added missing documentation. Removed redundant methods.
+
+## [1.0.0] - 2021-03-30
+
+Create a version object using a string or from component building a semantic version! You can also use the SemanticVersionComparable protocol to compare to version as much as you like or implement your own version object.
+
+## [0.6.0] - 2021-01-07
+
+Initial published setup of this package. Create a version from string, using major, minor, patch and extensions, from Bundle or from ProcessInfo. Compare two versions with common operators (==, ===, <, <=, >, >=) or get the severity of an update.
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Marius Hötten-Löns
+Copyright (c) 2021 Marius Felkner
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 [![doccov](https://mflknr.github.io/SwiftVersionCompare/badge.svg?sanitize=true)](https://mflknr.github.io/SwiftVersionCompare/)
 [![codecov](https://codecov.io/gh/mflknr/SwiftVersionCompare/branch/develop/graph/badge.svg?token=6EAG2J8DMU)](https://codecov.io/gh/mflknr/SwiftVersionCompare)
 
-A small package introducing a `Version` object implementing the  `SemanticVersionComparable` protocol for comparing versions conforming to [SemVer](https://semver.org). 
+A package introducing a `Version` object implementing the  `SemanticVersionComparable` protocol for comparing versions conforming to [SemVer](https://semver.org). 
 
 # Installation
 

diff --git a/Sources/SwiftVersionCompare/Helper/Character+Extensions.swift b/Sources/SwiftVersionCompare/Helper/Character+Extensions.swift
@@ -2,7 +2,7 @@
 //  Character+Extensions.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 30.03.21.
+//  Created by Marius Felkner on 30.03.21.
 //
 
 internal extension Character {

diff --git a/Sources/SwiftVersionCompare/Helper/Error.swift b/Sources/SwiftVersionCompare/Helper/Error.swift
diff --git a/Sources/SwiftVersionCompare/Helper/String+Regex.swift b/Sources/SwiftVersionCompare/Helper/String+Regex.swift
@@ -2,7 +2,7 @@
 //  String+Regex.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 05.01.21.
+//  Created by Marius Felkner on 05.01.21.
 //
 
 internal extension String {

diff --git a/Sources/SwiftVersionCompare/Helper/VersionCompareResult.swift b/Sources/SwiftVersionCompare/Helper/VersionCompareResult.swift
@@ -1,14 +1,13 @@
 //
-//  ComparisonResult.swift
+//  VersionCompareResult.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 06.01.21.
+//  Created by Marius Felkner on 06.01.21.
 //
 
 /// The severity of an update between versions.
 ///
-/// - Note: A difference between build-meta-data of versions are explicitly ignored, since `SemVer`  does not considere
-///         them to be different ranks.
+/// - Note: A difference between build-meta-data of versions are as `SemVer` states explicitly ignored.
 public enum VersionCompareResult {
     /// A `MAJOR`update
     case major

diff --git a/Sources/SwiftVersionCompare/Helper/VersionValidationError.swift b/Sources/SwiftVersionCompare/Helper/VersionValidationError.swift
@@ -0,0 +1,26 @@
+//
+//  VersionValidationError.swift
+//  SwiftVersionCompare
+//
+//  Created by Marius Felkner on 29.12.20.
+//
+
+import Foundation
+
+enum VersionValidationError: Swift.Error {
+    case invalidVersionIdentifier(identifier: String)
+}
+
+extension VersionValidationError: LocalizedError {
+    var errorDescription: String? {
+        switch self {
+        case .invalidVersionIdentifier(let identifier):
+            let format = NSLocalizedString(
+                "The parsed string contained an invalid SemVer version identifier: '%@'.",
+                comment: ""
+            )
+
+            return String(format: format, identifier)
+        }
+    }
+}
diff --git a/...nCompare/SemanticVersionComparable/BuildMetaData/BuildMetaData+ExpressibleByLiteral.swift b/...nCompare/SemanticVersionComparable/BuildMetaData/BuildMetaData+ExpressibleByLiteral.swift
@@ -2,7 +2,7 @@
 //  BuildMetaData+ExpressibleByLiteral.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 12.03.21.
+//  Created by Marius Felkner on 12.03.21.
 //
 
 extension BuildMetaData: LosslessStringConvertible {

diff --git a/Sources/SwiftVersionCompare/SemanticVersionComparable/BuildMetaData/BuildMetaData.swift b/Sources/SwiftVersionCompare/SemanticVersionComparable/BuildMetaData/BuildMetaData.swift
@@ -2,10 +2,10 @@
 //  BuildMetaData.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 12.03.21.
+//  Created by Marius Felkner on 12.03.21.
 //
 
-/// Typed build-meta-data.
+/// Enumerated build-meta-data for simple and `SemVer` conform access.
 ///
 /// - Note: Identifier can be described using alphanumeric letters or digits.
 ///

diff --git a/...mpare/SemanticVersionComparable/PrereleaseIdentifier/PrereleaseIdentifier+Equatable.swift b/...mpare/SemanticVersionComparable/PrereleaseIdentifier/PrereleaseIdentifier+Equatable.swift
@@ -2,7 +2,7 @@
 //  PrereleaseIdentifier+Equatable.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 12.03.21.
+//  Created by Marius Felkner on 12.03.21.
 //
 
 extension PrereleaseIdentifier {

diff --git a/...ticVersionComparable/PrereleaseIdentifier/PrereleaseIdentifier+ExpressibleByLiteral.swift b/...ticVersionComparable/PrereleaseIdentifier/PrereleaseIdentifier+ExpressibleByLiteral.swift
@@ -2,7 +2,7 @@
 //  PrereleaseIdentifier+ExpressibleByLiteral.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 12.03.21.
+//  Created by Marius Felkner on 12.03.21.
 //
 
 extension PrereleaseIdentifier: LosslessStringConvertible {

diff --git a/...tVersionCompare/SemanticVersionComparable/PrereleaseIdentifier/PrereleaseIdentifier.swift b/...tVersionCompare/SemanticVersionComparable/PrereleaseIdentifier/PrereleaseIdentifier.swift
@@ -2,10 +2,10 @@
 //  PrereleaseIdentifier.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 12.03.21.
+//  Created by Marius Felkner on 12.03.21.
 //
 
-/// Typed pre-release identifier.
+/// Enumerated pre-release identifier for `SemVer` conform initializing and handling.
 ///
 /// - Note: Identifier can be described using alphanumeric or numeric letters.
 ///

diff --git a/.../SwiftVersionCompare/SemanticVersionComparable/SemanticVersionComparable+Comparable.swift b/.../SwiftVersionCompare/SemanticVersionComparable/SemanticVersionComparable+Comparable.swift
@@ -2,7 +2,7 @@
 //  SemanticVersionComparable+Comparable.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 05.01.21.
+//  Created by Marius Felkner on 05.01.21.
 //
 
 public extension SemanticVersionComparable {

diff --git a/...s/SwiftVersionCompare/SemanticVersionComparable/SemanticVersionComparable+Equatable.swift b/...s/SwiftVersionCompare/SemanticVersionComparable/SemanticVersionComparable+Equatable.swift
@@ -2,7 +2,7 @@
 //  SemanticVersionComparable+Equatable.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 05.01.21.
+//  Created by Marius Felkner on 05.01.21.
 //
 
 public extension SemanticVersionComparable {

diff --git a/...es/SwiftVersionCompare/SemanticVersionComparable/SemanticVersionComparable+Hashable.swift b/...es/SwiftVersionCompare/SemanticVersionComparable/SemanticVersionComparable+Hashable.swift
@@ -2,7 +2,7 @@
 //  SemanticVersionComparable+Hashable.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 13.03.21.
+//  Created by Marius Felkner on 13.03.21.
 //
 
 extension SemanticVersionComparable {

diff --git a/Sources/SwiftVersionCompare/SemanticVersionComparable/SemanticVersionComparable.swift b/Sources/SwiftVersionCompare/SemanticVersionComparable/SemanticVersionComparable.swift
@@ -2,7 +2,7 @@
 //  SemanticVersionComparable.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 29.12.20.
+//  Created by Marius Felkner on 29.12.20.
 //
 
 /// A type that can be expressed as a semantic version conforming to `SemVer`.
@@ -42,16 +42,19 @@ public protocol SemanticVersionComparable: Comparable, Hashable {
 // MARK: -
 
 public extension SemanticVersionComparable {
-    /// A Boolean value indicating the compatibility of two versions.
+    /// 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 object that conforms to the `SemanticVersionComparable`protocol.
+    /// - Parameter version: An version object that conforms to the `SemanticVersionComparable`protocol.
     ///
     /// - Returns: `true` if both objects have equal major versions.
     func isCompatible(with version: Self) -> Bool {
         major == version.major
     }
 
-    /// Compare versions for their update severity.
+    /// 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.
     ///
     /// - Parameter version: The version you want to compare to another version.
     ///
@@ -94,6 +97,8 @@ public extension SemanticVersionComparable {
     /// - Parameter version: The other version you want to check with.
     ///
     /// - Returns: `true` if the respective version cores are equal.
+    ///
+    /// - Note: A version core is defined as the `MAJOR.MINOR.PATCH` part of a semantic version.
     func hasEqualVersionCore(as version: Self) -> Bool {
         let lhsAsIntSequence = [Int(major), Int(minor ?? 0), Int(patch ?? 0)]
         let rhsAsIntSequence = [Int(version.major), Int(version.minor ?? 0), Int(version.patch ?? 0)]
@@ -104,7 +109,8 @@ public extension SemanticVersionComparable {
 // MARK: - Accessors
 
 public extension SemanticVersionComparable {
-    /// The absolute string of the version.
+    /// The absolute string of the version containing the core version, pre-release identifier and build-meta-data
+    /// formatted as `MAJOR.MINOR.PATCH-PRERELEASE+BUILD`.
     var absoluteString: String {
         var versionString = coreString
         if let pr = prereleaseIdentifierString {
@@ -118,15 +124,15 @@ public extension SemanticVersionComparable {
         return versionString
     }
 
-    /// The string of the version representing `MAJOR.MINOR.PATCH`.
+    /// The string of the version representing `MAJOR.MINOR.PATCH` only.
     var coreString: String {
         [major, minor, patch]
             .compactMap { $0 }
             .map(String.init)
             .joined(separator: ".")
     }
 
-    /// The string of the version representing the pre-release identifier and build-meta-data.
+    /// The string of the version containing the pre-release identifier and build-meta-data only.
     var extensionString: String? {
         var extensionsString: String? = prereleaseIdentifierString
         if let build = buildMetaDataString {
@@ -147,7 +153,7 @@ public extension SemanticVersionComparable {
             .joined(separator: ".")
     }
 
-    /// The build meta data as a string if available.
+    /// The build-meta-data as a string if available.
     var buildMetaDataString: String? {
         build?
             .compactMap { $0.value }

diff --git a/Sources/SwiftVersionCompare/Version+Bundle.swift b/Sources/SwiftVersionCompare/Version+Bundle.swift
@@ -2,7 +2,7 @@
 //  Version+Bundle.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 05.01.21.
+//  Created by Marius Felkner on 05.01.21.
 //
 
 import Foundation

diff --git a/Sources/SwiftVersionCompare/Version+OS.swift b/Sources/SwiftVersionCompare/Version+OS.swift
@@ -2,7 +2,7 @@
 //  Version+OS.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 06.01.21.
+//  Created by Marius Felkner on 06.01.21.
 //
 
 import Foundation

diff --git a/Sources/SwiftVersionCompare/Version+StringInitializer.swift b/Sources/SwiftVersionCompare/Version+StringInitializer.swift
@@ -1,14 +1,14 @@
 //
-//  Version+StringOperators.swift
+//  Version+StringInitializer.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 05.01.21.
+//  Created by Marius Felkner on 05.01.21.
 //
 
 extension Version: LosslessStringConvertible {
     /// Creates a new version from a string.
     ///
-    /// - Parameter string: The string beeing parsed into a version.
+    /// - Parameter string: A string beeing parsed into a version.
     ///
     /// - Returns: A version object or `nil` if string does not conform to `SemVer`.
     public init?(_ string: String) {

diff --git a/Sources/SwiftVersionCompare/Version.swift b/Sources/SwiftVersionCompare/Version.swift
@@ -2,7 +2,7 @@
 //  Version.swift
 //  SwiftVersionCompare
 //
-//  Created by Marius Hötten-Löns on 29.12.20.
+//  Created by Marius Felkner on 29.12.20.
 //
 
 /// A version type conforming to `SemVer`.
@@ -24,7 +24,7 @@
 /// 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).
 ///
-///     let version: Version = let version: Version = Version(major: 1, minor: 0, patch: 0, prerelease: ["alpha"], build: ["500"])
+///     let version: Version = Version(major: 1, minor: 0, patch: 0, prerelease: ["alpha"], build: ["500"])
 ///     version.absoluteString // -> "1.0.0-alpha+500"
 ///
 ///     let version: Version = Version(2, 32, 16, ["family", .alpha], ["1"])
@@ -141,7 +141,7 @@ public struct Version: SemanticVersionComparable {
                     let element = UInt($0),
                     let firstCharacter = $0.first,
                     !(firstCharacter.isZero && $0.count > 1) else {
-                    throw Error.invalidVersionIdentifier
+                    throw VersionValidationError.invalidVersionIdentifier(identifier: $0)
                 }
 
                 return element

diff --git a/SwiftVersionCompare.xcodeproj/project.pbxproj b/SwiftVersionCompare.xcodeproj/project.pbxproj
@@ -22,7 +22,7 @@
 
 /* Begin PBXBuildFile section */
 		24828B622613B4EC00AF8BA2 /* Character+Extensions.swift in Sources */ = {isa = PBXBuildFile; fileRef = 24828B612613B4EC00AF8BA2 /* Character+Extensions.swift */; };
-		24A6A24625A3DD3B00E12D71 /* Error.swift in Sources */ = {isa = PBXBuildFile; fileRef = 24A6A24525A3DD3B00E12D71 /* Error.swift */; };
+		24A6A24625A3DD3B00E12D71 /* VersionValidationError.swift in Sources */ = {isa = PBXBuildFile; fileRef = 24A6A24525A3DD3B00E12D71 /* VersionValidationError.swift */; };
 		24A6A25925A5198900E12D71 /* String+Regex.swift in Sources */ = {isa = PBXBuildFile; fileRef = 24A6A25825A5198900E12D71 /* String+Regex.swift */; };
 		24A6A26425A51A2F00E12D71 /* SemanticVersionComparable+Equatable.swift in Sources */ = {isa = PBXBuildFile; fileRef = 24A6A26325A51A2F00E12D71 /* SemanticVersionComparable+Equatable.swift */; };
 		24A6A26A25A51A4700E12D71 /* SemanticVersionComparable+Comparable.swift in Sources */ = {isa = PBXBuildFile; fileRef = 24A6A26925A51A4700E12D71 /* SemanticVersionComparable+Comparable.swift */; };
@@ -65,7 +65,7 @@
 /* Begin PBXFileReference section */
 		24322B402613C4EC0028E151 /* .codecov.yml */ = {isa = PBXFileReference; lastKnownFileType = text.yaml; path = .codecov.yml; sourceTree = "<group>"; };
 		24828B612613B4EC00AF8BA2 /* Character+Extensions.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "Character+Extensions.swift"; sourceTree = "<group>"; };
-		24A6A24525A3DD3B00E12D71 /* Error.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = Error.swift; sourceTree = "<group>"; };
+		24A6A24525A3DD3B00E12D71 /* VersionValidationError.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = VersionValidationError.swift; sourceTree = "<group>"; };
 		24A6A25825A5198900E12D71 /* String+Regex.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "String+Regex.swift"; sourceTree = "<group>"; };
 		24A6A26325A51A2F00E12D71 /* SemanticVersionComparable+Equatable.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "SemanticVersionComparable+Equatable.swift"; sourceTree = "<group>"; };
 		24A6A26925A51A4700E12D71 /* SemanticVersionComparable+Comparable.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "SemanticVersionComparable+Comparable.swift"; sourceTree = "<group>"; };
@@ -80,6 +80,7 @@
 		24D6FFE425FB6FFE0003375E /* PrereleaseIdentifier.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PrereleaseIdentifier.swift; sourceTree = "<group>"; };
 		24D6FFEE25FB74CA0003375E /* PrereleaseIdentifier+ExpressibleByLiteral.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "PrereleaseIdentifier+ExpressibleByLiteral.swift"; sourceTree = "<group>"; };
 		24D6FFF525FB75210003375E /* BuildMetaData.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BuildMetaData.swift; sourceTree = "<group>"; };
+		24F8D48D26A96FD1007C72AE /* CHANGELOG.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = CHANGELOG.md; sourceTree = "<group>"; };
 		OBJ_10 /* SemanticVersionComparable.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SemanticVersionComparable.swift; sourceTree = "<group>"; };
 		OBJ_11 /* Version.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Version.swift; sourceTree = "<group>"; };
 		OBJ_14 /* SemanticVersionComparableTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SemanticVersionComparableTests.swift; sourceTree = "<group>"; };
@@ -115,9 +116,9 @@
 			isa = PBXGroup;
 			children = (
 				24828B612613B4EC00AF8BA2 /* Character+Extensions.swift */,
-				24A6A24525A3DD3B00E12D71 /* Error.swift */,
 				24A6A25825A5198900E12D71 /* String+Regex.swift */,
 				24B3A1CD261103BB00EDC055 /* VersionCompareResult.swift */,
+				24A6A24525A3DD3B00E12D71 /* VersionValidationError.swift */,
 			);
 			path = Helper;
 			sourceTree = "<group>";
@@ -190,6 +191,7 @@
 				OBJ_12 /* Tests */,
 				OBJ_17 /* Products */,
 				OBJ_20 /* LICENSE */,
+				24F8D48D26A96FD1007C72AE /* CHANGELOG.md */,
 				OBJ_21 /* README.md */,
 				24A6A2BB25A67D1200E12D71 /* .jazzy.yml */,
 				24322B402613C4EC0028E151 /* .codecov.yml */,
@@ -307,7 +309,7 @@
 				24A6A27E25A51E1900E12D71 /* Version+Bundle.swift in Sources */,
 				24A6A27025A51B5500E12D71 /* Version+StringInitializer.swift in Sources */,
 				24A6A28825A6002200E12D71 /* Version+OS.swift in Sources */,
-				24A6A24625A3DD3B00E12D71 /* Error.swift in Sources */,
+				24A6A24625A3DD3B00E12D71 /* VersionValidationError.swift in Sources */,
 				24B3A1CE261103BB00EDC055 /* VersionCompareResult.swift in Sources */,
 				24D6003625FCE1F60003375E /* SemanticVersionComparable+Hashable.swift in Sources */,
 				24D6FFE525FB6FFE0003375E /* PrereleaseIdentifier.swift in Sources */,