adding comments

Sources/SyndiKit/Formats/Feeds/Atom/AtomCategory.swift

@@ -1,3 +1,11 @@
+/**
+ A struct representing an Atom category.
+
+ - Note: This struct conforms to the `Codable` and `EntryCategory` protocols.
+
+ - SeeAlso: `EntryCategory`
+ */
 public struct AtomCategory: Codable, EntryCategory {
+  /// The term of the category.
   public let term: String
 }

Sources/SyndiKit/Formats/Feeds/Atom/AtomEntry.swift

@@ -1,80 +1,87 @@
 import Foundation
 
+/// A struct representing an entry in an Atom feed.
 public struct AtomEntry: Codable {
-  public enum CodingKeys: String, CodingKey {
-    case id
-    case title
-    case published
-    case content
-    case updated
-    case links = "link"
-    case authors = "author"
-    case atomCategories = "category"
-    case youtubeVideoID = "yt:videoId"
-    case youtubeChannelID = "yt:channelId"
-    case creators = "dc:creator"
-    case mediaGroup = "media:group"
-  }
-
   /// A permanent, universally unique identifier for an entry.
   public let id: EntryID
 
-  /// a Text construct that conveys a human-readable title
+  /// A human-readable title for the entry.
   public let title: String
 
-  /// The most recent instant in time when the entry was published
+  /// The most recent instant in time when the entry was published.
   public let published: Date?
 
-  /// Content of the trny.
+  /// The content of the entry.
   public let content: String?
 
-  /// The most recent instant in time when the entry was modified in a way
-  /// the publisher considers significant.
+  /// The most recent instant in time when the entry was modified.
   public let updated: Date
 
-  /// Cateogires of the entry.
+  /// The categories associated with the entry.
   public let atomCategories: [AtomCategory]
 
-  /// a reference to a Web resource.
+  /// The links associated with the entry.
   public let links: [Link]
-  /// The author of the entry.
-  public let authors: [Author]
 
-  /// YouTube channel ID, if from a YouTube channel.
-  public let youtubeChannelID: String?
+  /// The authors of the entry.
+  public let authors: [Author]
 
-  /// YouTube video ID, if from a YouTube channel.
+  /// The YouTube video ID, if the entry is from a YouTube channel.
   public let youtubeVideoID: String?
 
-  ///  the person or entity who wrote an item
+  /// The YouTube channel ID, if the entry is from a YouTube channel.
+  public let youtubeChannelID: String?
+
+  /// The creators of the entry.
   public let creators: [String]
 
-  /// Grouping of <media:content> elements that are effectively the same content,
-  /// yet different representations.
+  /// The media group associated with the entry.
   public let mediaGroup: AtomMediaGroup?
+
+  /// The coding keys used for encoding and decoding.
+  public enum CodingKeys: String, CodingKey {
+    case id
+    case title
+    case published
+    case content
+    case updated
+    case links = "link"
+    case authors = "author"
+    case atomCategories = "category"
+    case youtubeVideoID = "yt:videoId"
+    case youtubeChannelID = "yt:channelId"
+    case creators = "dc:creator"
+    case mediaGroup = "media:group"
+  }
 }
 
 extension AtomEntry: Entryable {
+  /// The categories associated with the entry.
   public var categories: [EntryCategory] {
     atomCategories
   }
 
+  /// The URL of the entry.
   public var url: URL? {
     links.first?.href
   }
 
+  /// The HTML content of the entry.
   public var contentHtml: String? {
     content?.trimmingCharacters(in: .whitespacesAndNewlines)
   }
 
+  /// The summary of the entry.
   public var summary: String? {
     nil
   }
 
+  /// The media content of the entry.
   public var media: MediaContent? {
     YouTubeIDProperties(entry: self).map(Video.youtube).map(MediaContent.video)
   }
 
+  /// The URL of the entry's image.
   public var imageURL: URL? {
     mediaGroup?.thumbnails.first?.url
   }

Sources/SyndiKit/Formats/Feeds/Atom/AtomFeed.swift

@@ -1,23 +1,12 @@
 import Foundation
 
-/// An XML-based Web content and metadata syndication format.
-///
-/// Based on the
-/// [specifications here](https://datatracker.ietf.org/doc/html/rfc4287#section-4.1.2).
-public struct AtomFeed {
-  public enum CodingKeys: String, CodingKey {
-    case id
-    case title
-    case description
-    case subtitle
-    case published
-    case pubDate
-    case links = "link"
-    case entries = "entry"
-    case authors = "author"
-    case youtubeChannelID = "yt:channelId"
-  }
+/**
+ An XML-based Web content and metadata syndication format.
 
+ Based on the
+ [specifications here](https://datatracker.ietf.org/doc/html/rfc4287#section-4.1.2).
+ */
+public struct AtomFeed {
   /// Identifies the feed using a universally unique and permanent URI.
   /// If you have a long-term, renewable lease on your Internet domain name,
   /// then you can feel free to use your website's address.
@@ -27,10 +16,10 @@ public struct AtomFeed {
   /// Often the same as the title of the associated website.
   public let title: String
 
-  /// Contains a human-readable description or subtitle for the feed
+  /// Contains a human-readable description or subtitle for the feed.
   public let description: String?
 
-  /// Contains a human-readable description or subtitle for the feed
+  /// Contains a human-readable description or subtitle for the feed.
   public let subtitle: String?
 
   /// The publication date for the content in the channel.
@@ -39,12 +28,12 @@ public struct AtomFeed {
   /// The publication date for the content in the channel.
   public let pubDate: Date?
 
-  /// a reference from an entry or feed to a Web resource.
+  /// A reference from an entry or feed to a Web resource.
   public let links: [Link]
 
-  /// An individual entry,
-  /// acting as a container for metadata and data associated with the entry
+  /// Individual entries of the feed.
   public let entries: [AtomEntry]
+
   /// The author of the feed.
   public let authors: [Author]
 
@@ -53,34 +42,43 @@ public struct AtomFeed {
 }
 
 extension AtomFeed: DecodableFeed {
+  /// The source of the decoder for AtomFeed.
   internal static let source: DecoderSetup = DecoderSource.xml
 
+  /// The label for AtomFeed.
   internal static let label: String = "Atom"
 
+  /// The summary of the AtomFeed.
   public var summary: String? {
     description ?? subtitle
   }
 
+  /// The children of the AtomFeed.
   public var children: [Entryable] {
     entries
   }
 
+  /// The site URL of the AtomFeed.
   public var siteURL: URL? {
     links.first { $0.rel != "self" }?.href
   }
 
+  /// The updated date of the AtomFeed.
   public var updated: Date? {
     pubDate ?? published
   }
 
+  /// The copyright of the AtomFeed.
   public var copyright: String? {
     nil
   }
 
+  /// The image URL of the AtomFeed.
   public var image: URL? {
     nil
   }
 
+  /// The syndication update of the AtomFeed.
   public var syndication: SyndicationUpdate? {
     nil
   }

Sources/SyndiKit/Formats/Feeds/Atom/AtomMedia.swift

@@ -1,18 +1,21 @@
 import Foundation
 
-/// Media structure which enables
-/// content publishers and bloggers to syndicate multimedia content
-/// such as TV and video clips, movies, images and audio.
-///
-/// Fore more detils check out
-/// [the Media RSS Specification](https://www.rssboard.org/media-rss).
+/**
+ Media structure which enables content publishers and bloggers
+ to syndicate multimedia content such as TV and video clips, movies, images and audio.
+
+ For more details, check out
+ [the Media RSS Specification](https://www.rssboard.org/media-rss).
+ */
 public struct AtomMedia: Codable {
-  /// The type of object.
-  ///
-  ///  While this attribute can at times seem redundant if type is supplied,
-  ///  it is included because it simplifies decision making on the reader side,
-  ///  as well as flushes out any ambiguities between MIME type and object type.
-  ///  It is an optional attribute.
+  /**
+   The type of object.
+
+   While this attribute can at times seem redundant if type is supplied,
+   it is included because it simplifies decision making on the reader side,
+   as well as flushes out any ambiguities between MIME type and object type.
+   It is an optional attribute.
+   */
   public let url: URL
 
   /// The direct URL to the media object.

Sources/SyndiKit/Formats/Feeds/Atom/AtomMediaGroup.swift

@@ -1,15 +1,24 @@
 import Foundation
 
+/// A group of media elements in an Atom feed.
 public struct AtomMediaGroup: Codable {
+  /// Coding keys for encoding and decoding.
   public enum CodingKeys: String, CodingKey {
     case title = "media:title"
     case descriptions = "media:description"
     case contents = "media:content"
     case thumbnails = "media:thumbnail"
   }
 
+  /// The title of the media group.
   public let title: String?
+
+  /// The media elements within the group.
   public let contents: [AtomMedia]
+
+  /// The thumbnail images associated with the media group.
   public let thumbnails: [AtomMedia]
+
+  /// The descriptions of the media group.
   public let descriptions: [String]
 }

Sources/SyndiKit/Formats/Feeds/JSONFeed/JSONFeed.swift

@@ -1,52 +1,80 @@
 import Foundation
 
+/**
+ A struct representing a JSON feed.
+
+ - Note: This struct conforms to the `DecodableFeed` protocol.
+
+ - SeeAlso: `DecodableFeed`
+ */
 public struct JSONFeed {
+  /// The version of the JSON feed.
   public let version: URL
+
+  /// The title of the JSON feed.
   public let title: String
+
+  /// The URL of the home page associated with the feed.
   public let homePageUrl: URL
+
+  /// A description of the JSON feed.
   public let description: String?
 
   /// The author of the feed.
   public let author: Author?
+
+  /// The items in the JSON feed.
   public let items: [JSONItem]
 }
 
 extension JSONFeed: DecodableFeed {
+  /// The source of the decoder for JSON feed.
   internal static let source: DecoderSetup = DecoderSource.json
+
+  /// The label for the JSON feed.
   internal static let label: String = "JSON"
 
+  /// The YouTube channel ID associated with the feed.
   public var youtubeChannelID: String? {
     nil
   }
 
+  /// The children of the JSON feed.
   public var children: [Entryable] {
     items
   }
 
+  /// The summary of the JSON feed.
   public var summary: String? {
     description
   }
 
+  /// The site URL associated with the feed.
   public var siteURL: URL? {
     homePageUrl
   }
 
+  /// The last updated date of the JSON feed.
   public var updated: Date? {
     nil
   }
 
+  /// The copyright information of the JSON feed.
   public var copyright: String? {
     nil
   }
 
+  /// The image URL associated with the feed.
   public var image: URL? {
     nil
   }
 
+  /// The syndication update information of the JSON feed.
   public var syndication: SyndicationUpdate? {
     nil
   }
 
+  /// The authors of the JSON feed.
   public var authors: [Author] {
     guard let author = author else {
       return []