Update documentation and deprecate no longer needed types

Author: danielsaidi

RELEASE_NOTES.md

@@ -11,6 +11,12 @@ These release notes cover the current major version. See older versions for olde
 
 
 
+## 6.1
+
+This version bumps the package to 6.1 and deprecates some list views.
+
+
+
 ## 6.0
 
 This version removes all deprecations, which means that many parts of the library are no longer available.

Sources/SwiftUIKit/Collections/Array+Range.swift

@@ -10,8 +10,7 @@ import Foundation
 
 public extension Array where Element: Comparable & Strideable {
 
-    /// Create an array with values from a `range`, stepping
-    /// `stepSize` between each value.
+    /// Create an array from a `range` with `stepSize` between each value.
     init(
         _ range: ClosedRange<Element>,
         stepSize: Element.Stride

Sources/SwiftUIKit/Collections/Sequence+Group.swift

@@ -12,8 +12,7 @@ public extension Sequence {
 
     /// Group the sequence into a dictionary.
     ///
-    /// The operation can use any property from the items as
-    /// the dictionary key.
+    /// The operation can use any element property as dictionary key.
     func grouped<T>(by grouper: (Element) -> T) -> [T: [Element]] {
         Dictionary(grouping: self, by: grouper)
     }

Sources/SwiftUIKit/Colors/Color+Codable.swift

@@ -22,14 +22,17 @@ import AppKit
 #endif
 
 /// This extension makes `Color` implement `Codable`.
-extension Color: Codable {
-    
+extension Color: @retroactive Decodable {}
+extension Color: @retroactive Encodable {}
+
+public extension Color {
+
     enum CodingKeys: String, CodingKey {
         case red, green, blue, alpha
     }
 
     /// Initialize a color value from a decoder.
-    public init(from decoder: Decoder) throws {
+    init(from decoder: Decoder) throws {
         let container = try decoder.container(keyedBy: CodingKeys.self)
         let r = try container.decode(Double.self, forKey: .red)
         let g = try container.decode(Double.self, forKey: .green)
@@ -40,10 +43,9 @@ extension Color: Codable {
 
     /// Encode the color, using an encoder.
     ///
-    /// Note that encoding colors that support features like
-    /// dark mode, high contrast etc. will cause the encoded
-    /// colors to only contain the current color information.
-    public func encode(to encoder: Encoder) throws {
+    /// > Important: Encoding colors that support system features like dark mode,
+    /// high contrast etc. will cause the encoded colors to be non-dynamic.
+    func encode(to encoder: Encoder) throws {
         guard let colorComponents = self.colorComponents else { return }
         var container = encoder.container(keyedBy: CodingKeys.self)
         try container.encode(colorComponents.red, forKey: .red)
@@ -69,13 +71,8 @@ private extension Color {
 
         #if os(macOS)
         SystemColor(self).getRed(&r, green: &g, blue: &b, alpha: &a)
-        // Note that non RGB color will raise an exception, that I don't now how to catch because it is an Objc exception.
         #else
-        guard SystemColor(self).getRed(&r, green: &g, blue: &b, alpha: &a) else {
-            // Pay attention that the color should be convertible into RGB format
-            // Colors using hue, saturation and brightness won't work
-            return nil
-        }
+        guard SystemColor(self).getRed(&r, green: &g, blue: &b, alpha: &a) else { return nil }
         #endif
 
         return (r, g, b, a)

Sources/SwiftUIKit/Colors/Color+Hex.swift

@@ -22,8 +22,7 @@ public extension Color {
 
     /// Create a color with a string hex, e.g. `#abcdef`,
     ///
-    /// This supports multiple string formats, like `abcdef`,
-    /// `#abcdef`, `0xabcdef`, and `#abcdef`.
+    /// This supports `abcdef`, `#abcdef`, `0xabcdef`, and `#abcdef`.
     ///
     /// - Parameters:
     ///   - hex: The hex string to parse.
@@ -44,8 +43,7 @@ public extension Color {
 
     /// Create a color with a string hex, e.g. `#abcdef`,
     ///
-    /// This supports multiple string formats, like `abcdef`,
-    /// `#abcdef`, `0xabcdef`, and `#abcdef`.
+    /// This supports `abcdef`, `#abcdef`, `0xabcdef`, and `#abcdef`.
     ///
     /// - Parameters:
     ///   - hex: The hex string to parse.
@@ -80,8 +78,7 @@ public extension Color {
     return Preview()
 }
 
-/// This extension extends `ColorRepresentable` with ways to
-/// be created with hex strings and int values.
+/// This extension extends `ColorRepresentable` with hex-based initializers.
 public extension ColorRepresentable {
 
     /// Initialize a color with a hex value, e.g. `0xabcdef`.
@@ -98,8 +95,7 @@ public extension ColorRepresentable {
 
     /// Initialize a color with a hex string, e.g. `#abcdef`.
     ///
-    /// This supports multiple string formats, like `abcdef`,
-    /// `#abcdef`, `0xabcdef`, and `#abcdef`.
+    /// This supports `abcdef`, `#abcdef`, `0xabcdef`, and `#abcdef`.
     ///
     /// - Parameters:
     ///   - hex: The hex string to parse.

Sources/SwiftUIKit/Colors/Color+Random.swift

@@ -15,7 +15,7 @@ public extension Color {
     ///
     /// - Parameters:
     ///   - range: The random color range, by default `0...1`.
-    ///   - randomOpacity: Whether or not to randomize opacity as well, by default `false`.
+    ///   - randomOpacity: Whether to randomize opacity, by default `false`.
     static func random(
         in range: ClosedRange<Double> = 0...1,
         randomOpacity: Bool = false

Sources/SwiftUIKit/Data/Collection+Codable.swift

@@ -11,13 +11,11 @@
 import Foundation
 import SwiftUI
 
-/// This extension makes `Array` able to store Codable types,
-/// by serializing the collection to JSON.
+/// This extension makes `Array` able to store `Codable` types.
 ///
-/// > Important: JSON encoding may cause important type data
-/// to disappear. For instance, JSON encoding a `Color` will
-/// not include any information about alternate color values
-/// for light and dark mode, high constrasts, etc.
+/// > Important: Values will be encoded and decoded with JSON. This may cause
+/// loss of important data. For instance, a JSON encoded `Color` will not include
+/// any dynamic color information, like dark mode and high contrast variants.
 extension Array: @retroactive RawRepresentable where Element: Codable {
 
     public init?(rawValue: String) {
@@ -37,13 +35,11 @@ extension Array: @retroactive RawRepresentable where Element: Codable {
     }
 }
 
-/// This extension makes `Dictionary` able to store `Codable`
-/// types, by serializing the collection to JSON.
+/// This extension makes `Dictionary` able to store `Codable` types.
 ///
-/// > Important: JSON encoding may cause important type data
-/// to disappear. For instance, JSON encoding a `Color` will
-/// not include any information about alternate color values
-/// for light and dark mode, high constrasts, etc.
+/// > Important: Values will be encoded and decoded with JSON. This may cause
+/// loss of important data. For instance, a JSON encoded `Color` will not include
+/// any dynamic color information, like dark mode and high contrast variants.
 extension Dictionary: @retroactive RawRepresentable where Key: Codable, Value: Codable {
 
     public init?(rawValue: String) {

Sources/SwiftUIKit/Data/CsvParser.swift

@@ -8,12 +8,10 @@
 
 import Foundation
 
-/**
- This type can parse comma-separated value files and strings.
-
- When parsing a CSV file or string, every line will be split
- up into components, using the provided `componentSeparator`.
- */
+/// This type can parse comma-separated value files and strings.
+///
+/// When parsing a CSV file or string, each line will be split up into components by
+/// splitting the string with the provided `componentSeparator`.
 public class CsvParser {
 
     /// Create a CSV parser.

Sources/SwiftUIKit/Data/MimeType.swift

@@ -10,10 +10,6 @@ import Foundation
 import UniformTypeIdentifiers
 
 /// This enum defines different MIME and file types.
-///
-/// Note that some types are expected to be a different type,
-/// but instead use `application`. For instance, `json` is a
-/// text format, but the mime type is `application/json`.
 public enum MimeType: Identifiable {
 
     case

Sources/SwiftUIKit/Data/StorageValue.swift

@@ -11,16 +11,12 @@
 import Foundation
 import SwiftUI
 
-/// This type can wrap any `Codable` type to make it able to
-/// store the value in `AppStorage` and `SceneStorage`.
+/// This type can be used to wrap any `Codable` type, to let us store that value
+/// as JSON in `AppStorage` and `SceneStorage`.
 ///
-/// This type uses `JSONEncoder` and `JSONDecoder` to encode
-/// the value to data then decode it back to the source type.
-///
-/// > Important: JSON encoding may cause important type data
-/// to disappear. For instance, JSON encoding a `Color` will
-/// not include any information about alternate color values
-/// for light and dark mode, high constrasts, etc.
+/// > Important: Values will be encoded and decoded with JSON. This may cause
+/// loss of important data. For instance, a JSON encoded `Color` will not include
+/// any dynamic color information, like dark mode and high contrast variants. 
 public struct StorageValue<Value: Codable>: RawRepresentable {
 
     /// Create a storage value.