Adding Documentation Comments

.swiftlint.yml

@@ -110,6 +110,12 @@ function_parameter_count: 8
 line_length:
   - 90
   - 90
+type_name:
+  excluded:
+    - iTunesDuration
+    - iTunesEpisode
+    - iTunesOwner
+    - iTunesImage
 identifier_name:
   excluded:
     - id

Sources/SyndiKit/Common/EntryCategory.swift

@@ -1,4 +1,5 @@
 /// Abstract category type.
 public protocol EntryCategory {
+  /// Term used for the category
   var term: String { get }
 }

Sources/SyndiKit/Common/Primitives/CData.swift

@@ -1,5 +1,4 @@
 /// #CDATA XML element.
-public typealias StringLiteralType = String
 public struct CData: Codable, ExpressibleByStringLiteral, Equatable {
   public enum CodingKeys: String, CodingKey {
     case value = "#CDATA"

Sources/SyndiKit/Common/Primitives/XMLStringInt.swift

@@ -1,8 +1,8 @@
-/// XML Element which contains a `String` parsable into a `Integer`.
+/// XML Element which contains a ``String`` parsable into a ``Integer``.
 public struct XMLStringInt: Codable, ExpressibleByIntegerLiteral {
   public typealias IntegerLiteralType = Int
 
-  /// The underlying `Int` value.
+  /// The underlying ``Int`` value.
   public let value: Int
 
   public init(integerLiteral value: Int) {

Sources/SyndiKit/Decoding/SynDecoder.swift

@@ -77,7 +77,7 @@ public class SynDecoder {
     self.defaultXMLDecoderSetup = defaultXMLDecoderSetup ?? Self.setupXMLDecoder(_:)
   }
 
-  /// Creates an instance of `RSSDecoder`
+  /// Creates an instance of ``RSSDecoder``
   public convenience init() {
     self.init(types: nil, defaultJSONDecoderSetup: nil, defaultXMLDecoderSetup: nil)
   }
@@ -93,9 +93,9 @@ public class SynDecoder {
     decoder.trimValueWhitespaces = false
   }
 
-  /// Returns a `Feedable` object of the type you specify, decoded from a JSON object.
+  /// Returns a ``Feedable`` object of the type you specify, decoded from a JSON object.
   /// - Parameter data: The JSON or XML object to decode.
-  /// - Returns: A `Feedable` object
+  /// - Returns: A ``Feedable`` object
   ///
   /// If the data is not valid RSS, this method throws the
   /// `DecodingError.dataCorrupted(_:)` error.

Sources/SyndiKit/Formats/Blogs/CategoryDescriptor.swift

@@ -1,4 +1,16 @@
+/// A struct representing an Atom category.
+/// A descriptor for a category.
+///
+/// - Note: This struct is publicly accessible.
+///
+/// - Important: The ``title`` and ``description`` properties are read-only.
+///
+/// - SeeAlso: ``Category``
+/// - SeeAlso: ``EntryCategory``
 public struct CategoryDescriptor {
+  /// The title of the category.
   public let title: String
+
+  /// The description of the category.
   public let description: String
 }

Sources/SyndiKit/Formats/Blogs/CategoryLanguage.swift

@@ -1,8 +1,33 @@
+/// A struct representing an Atom category.
+/// A struct representing a category in a specific language.
+///
+/// - Parameters:
+///   - languageCategory: The category in a specific language.
+///   - language: The language of the category.
+///
+/// - Note: This struct is used internally.
+///
+/// - SeeAlso: ``SiteCategoryType``
+/// - SeeAlso: ``CategoryDescriptor``
+/// - SeeAlso: ``SiteLanguageType``
+/// - SeeAlso: ``EntryCategory``
 public struct CategoryLanguage {
+  /// The type of the category.
   public let type: SiteCategoryType
+
+  /// The descriptor of the category.
   public let descriptor: CategoryDescriptor
+
+  /// The language of the category.
   public let language: SiteLanguageType
 
+  /// A struct representing an Atom category.
+  ///   Initializes a ``CategoryLanguage`` instance.
+  ///
+  ///   - Parameters:
+  ///     - languageCategory: The category in a specific language.
+  ///     - language: The language of the category.
+  /// - SeeAlso: ``EntryCategory``
   internal init(languageCategory: SiteLanguageCategory, language: SiteLanguageType) {
     type = languageCategory.slug
     descriptor = CategoryDescriptor(

Sources/SyndiKit/Formats/Blogs/Site.swift

@@ -1,14 +1,34 @@
 import Foundation
 
+/// A struct representing a website.
 public struct Site {
+  /// The title of the website.
   public let title: String
+
+  /// The author of the website.
   public let author: String
+
+  /// The URL of the website.
   public let siteURL: URL
+
+  /// The URL of the website's feed.
   public let feedURL: URL
+
+  /// The URL of the website's Twitter page, if available.
   public let twitterURL: URL?
+
+  /// The category of the website.
   public let category: SiteCategoryType
+
+  /// The language of the website.
   public let language: SiteLanguageType
 
+  /// Initializes a new ``Site`` instance.
+  ///
+  /// - Parameters:
+  ///   - site: The `SiteLanguageCategory.Site` instance to use as a base.
+  ///   - categoryType: The category type of the website.
+  ///   - languageType: The language type of the website.
   internal init(
     site: SiteLanguageCategory.Site,
     categoryType: SiteCategoryType,

Sources/SyndiKit/Formats/Blogs/SiteCategory.swift

@@ -1,7 +1,35 @@
+/// A struct representing an Atom category.
+/// A struct representing a site category.
+///
+/// - Note: This struct is used to categorize sites based on their type and descriptors.
+///
+/// - Parameters:
+///   - type: The type of the site category.
+///   - descriptors: A dictionary mapping site language types to category descriptors.
+///
+/// - Important: This struct should not be used directly.
+/// Instead, use the ``SiteCategoryBuilder`` to create instances of ``SiteCategory``.
+///
+/// - SeeAlso: ``SiteCategoryType``
+/// - SeeAlso: ``CategoryDescriptor``
+/// - SeeAlso: ``CategoryLanguage``
+/// - SeeAlso: ``SiteCategoryBuilder``
+/// - SeeAlso: ``EntryCategory``
 public struct SiteCategory {
+  /// The type of the site category.
   public let type: SiteCategoryType
+
+  /// A dictionary mapping site language types to category descriptors.
   public let descriptors: [SiteLanguageType: CategoryDescriptor]
 
+  /// A struct representing an Atom category.
+  ///   Initializes a ``SiteCategory`` instance with the given languages.
+  ///
+  ///   - Parameter languages: An array of ``CategoryLanguage`` instances.
+  ///
+  ///   - Returns: A new ``SiteCategory`` instance
+  ///   if at least one language is provided, ``nil`` otherwise.
+  /// - SeeAlso: ``EntryCategory``
   internal init?(languages: [CategoryLanguage]) {
     guard let type = languages.first?.type else {
       return nil

Sources/SyndiKit/Formats/Blogs/SiteCategoryType.swift

@@ -1 +1,2 @@
+/// A type alias representing a site category.
 public typealias SiteCategoryType = String

Sources/SyndiKit/Formats/Blogs/SiteCollection.swift

@@ -1 +1,2 @@
+/// A collection of site language content.
 public typealias SiteCollection = [SiteLanguageContent]

Sources/SyndiKit/Formats/Blogs/SiteDirectory.swift

@@ -1,55 +1,58 @@
 import Foundation
 
+/// A directory of site collections.
 public struct SiteCollectionDirectory: SiteDirectory {
+  /// A sequence of sites.
   public typealias SiteSequence = [Site]
 
-  public typealias LanguageSequence =
-    Dictionary<SiteLanguageType, SiteLanguage>.Values
+  /// A sequence of languages.
+  public typealias LanguageSequence = Dictionary<SiteLanguageType, SiteLanguage>.Values
 
-  public typealias CategorySequence =
-    Dictionary<SiteCategoryType, SiteCategory>.Values
+  /// A sequence of categories.
+  public typealias CategorySequence = Dictionary<SiteCategoryType, SiteCategory>.Values
 
+  /// The internal structure of the site collection directory.
   internal struct Instance {
     internal let allSites: [Site]
     internal let languageDictionary: [SiteLanguageType: SiteLanguage]
     internal let categoryDictionary: [SiteCategoryType: SiteCategory]
-    internal let languageIndicies: [SiteLanguageType: Set<Int>]
-    internal let categoryIndicies: [SiteCategoryType: Set<Int>]
+    internal let languageIndices: [SiteLanguageType: Set<Int>]
+    internal let categoryIndices: [SiteCategoryType: Set<Int>]
 
     // swiftlint:disable:next function_body_length
     internal func sites(
       withLanguage language: SiteLanguageType?,
       withCategory category: SiteCategoryType?
     ) -> [Site] {
-      let languageIndicies: Set<Int>?
+      let languageIndices: Set<Int>?
       if let language = language {
-        languageIndicies = self.languageIndicies[language] ?? .init()
+        languageIndices = self.languageIndices[language] ?? .init()
       } else {
-        languageIndicies = nil
+        languageIndices = nil
       }
 
-      let categoryIndicies: Set<Int>?
+      let categoryIndices: Set<Int>?
       if let category = category {
-        categoryIndicies = self.categoryIndicies[category] ?? .init()
+        categoryIndices = self.categoryIndices[category] ?? .init()
       } else {
-        categoryIndicies = nil
+        categoryIndices = nil
       }
 
-      var indicies: Set<Int>?
+      var indices: Set<Int>?
 
-      if let languageIndicies = languageIndicies {
-        indicies = languageIndicies
+      if let languageIndices = languageIndices {
+        indices = languageIndices
       }
 
-      if let categoryIndicies = categoryIndicies {
-        if let current = indicies {
-          indicies = current.intersection(categoryIndicies)
+      if let categoryIndices = categoryIndices {
+        if let current = indices {
+          indices = current.intersection(categoryIndices)
         } else {
-          indicies = categoryIndicies
+          indices = categoryIndices
         }
       }
 
-      if let current = indicies {
+      if let current = indices {
         return current.map { self.allSites[$0] }
       } else {
         return allSites
@@ -61,14 +64,14 @@ public struct SiteCollectionDirectory: SiteDirectory {
       var categories = [CategoryLanguage]()
       var languages = [SiteLanguage]()
       var sites = [Site]()
-      var languageIndicies = [SiteLanguageType: Set<Int>]()
-      var categoryIndicies = [SiteCategoryType: Set<Int>]()
+      var languageIndices = [SiteLanguageType: Set<Int>]()
+      var categoryIndices = [SiteCategoryType: Set<Int>]()
 
       for languageContent in blogs {
         let language = SiteLanguage(content: languageContent)
-        var thisLanguageIndicies = [Int]()
+        var thisLanguageIndices = [Int]()
         for languageCategory in languageContent.categories {
-          var thisCategoryIndicies = [Int]()
+          var thisCategoryIndices = [Int]()
           let category = CategoryLanguage(
             languageCategory: languageCategory,
             language: language.type
@@ -81,13 +84,13 @@ public struct SiteCollectionDirectory: SiteDirectory {
               languageType: language.type
             )
             sites.append(site)
-            thisCategoryIndicies.append(index)
-            thisLanguageIndicies.append(index)
+            thisCategoryIndices.append(index)
+            thisLanguageIndices.append(index)
           }
-          categoryIndicies.formUnion(thisCategoryIndicies, key: category.type)
+          categoryIndices.formUnion(thisCategoryIndices, key: category.type)
           categories.append(category)
         }
-        languageIndicies.formUnion(thisLanguageIndicies, key: language.type)
+        languageIndices.formUnion(thisLanguageIndices, key: language.type)
         languages.append(language)
       }
 
@@ -96,30 +99,37 @@ public struct SiteCollectionDirectory: SiteDirectory {
       languageDictionary = Dictionary(
         uniqueKeysWithValues: languages.map { ($0.type, $0) }
       )
-      self.languageIndicies = languageIndicies
-      self.categoryIndicies = categoryIndicies
+      self.languageIndices = languageIndices
+      self.categoryIndices = categoryIndices
       allSites = sites
     }
   }
 
   private let instance: Instance
 
-  public var languages: Dictionary<
-    SiteLanguageType, SiteLanguage
-  >.Values {
+  /// A sequence of languages in the site collection directory.
+  public var languages: Dictionary<SiteLanguageType, SiteLanguage>.Values {
     instance.languageDictionary.values
   }
 
-  public var categories: Dictionary<
-    SiteCategoryType, SiteCategory
-  >.Values {
+  /// A sequence of categories in the site collection directory.
+  public var categories: Dictionary<SiteCategoryType, SiteCategory>.Values {
     instance.categoryDictionary.values
   }
 
+  /// Initializes a new instance of the ``SiteCollectionDirectory`` struct.
+  ///
+  /// - Parameter blogs: The site collection to use.
   internal init(blogs: SiteCollection) {
     instance = .init(blogs: blogs)
   }
 
+  /// Retrieves a list of sites based on the specified language and category.
+  ///
+  /// - Parameters:
+  ///   - language: The language of the sites to retrieve.
+  ///   - category: The category of the sites to retrieve.
+  /// - Returns: A list of sites matching the specified language and category.
   public func sites(
     withLanguage language: SiteLanguageType?,
     withCategory category: SiteCategoryType?
@@ -128,24 +138,40 @@ public struct SiteCollectionDirectory: SiteDirectory {
   }
 }
 
+/// A protocol for site directories.
 public protocol SiteDirectory {
-  associatedtype SiteSequence: Sequence
-    where SiteSequence.Element == Site
-  associatedtype LanguageSequence: Sequence
-    where LanguageSequence.Element == SiteLanguage
-  associatedtype CategorySequence: Sequence
-    where CategorySequence.Element == SiteCategory
-
+  /// List of Sites
+  associatedtype SiteSequence: Sequence where SiteSequence.Element == Site
+  /// List of Languages
+  associatedtype LanguageSequence: Sequence where LanguageSequence.Element == SiteLanguage
+  /// List of Categories
+  associatedtype CategorySequence: Sequence where CategorySequence.Element == SiteCategory
+
+  /// A sequence of languages in the site directory.
   var languages: LanguageSequence { get }
+
+  /// A sequence of categories in the site directory.
   var categories: CategorySequence { get }
 
+  /// Retrieves a list of sites based on the specified language and category.
+  ///
+  /// - Parameters:
+  ///   - language: The language of the sites to retrieve.
+  ///   - category: The category of the sites to retrieve.
+  /// - Returns: A list of sites matching the specified language and category.
   func sites(
     withLanguage language: SiteLanguageType?,
     withCategory category: SiteCategoryType?
   ) -> SiteSequence
 }
 
 extension SiteDirectory {
+  /// Retrieves a list of sites based on the specified language and category.
+  ///
+  /// - Parameters:
+  ///   - language: The language of the sites to retrieve.
+  ///   - category: The category of the sites to retrieve.
+  /// - Returns: A list of sites matching the specified language and category.
   public func sites(
     withLanguage language: SiteLanguageType? = nil,
     withCategory category: SiteCategoryType? = nil