fixing documentation comments

Sources/SyndiKit/Formats/Blogs/CategoryDescriptor.swift

@@ -1,12 +1,12 @@
-/**
- A descriptor for a category.
-
- - Note: This struct is publicly accessible.
-
- - Important: The `title` and `description` properties are read-only.
-
- - SeeAlso: `Category`
- */
+/// 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

Sources/SyndiKit/Formats/Blogs/CategoryLanguage.swift

@@ -1,16 +1,16 @@
-/**
- 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`
- */
+/// 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
@@ -21,13 +21,13 @@ public struct CategoryLanguage {
   /// The language of the category.
   public let language: SiteLanguageType
 
-  /**
-   Initializes a `CategoryLanguage` instance.
-
-   - Parameters:
-     - languageCategory: The category in a specific language.
-     - language: The language of the category.
-   */
+  /// 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/SiteCategory.swift

@@ -1,35 +1,35 @@
-/**
- 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`
- */
+/// 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]
 
-  /**
-   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.
-   */
+  /// 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/SiteDirectoryBuilder.swift

@@ -5,13 +5,13 @@ public struct SiteCollectionDirectoryBuilder: SiteDirectoryBuilder {
   /// Initializes a new instance of `SiteCollectionDirectoryBuilder`.
   public init() {}
 
-  /**
-   Creates a site collection directory from a site collection.
-
-   - Parameter blogs: The site collection to build the directory from.
-
-   - Returns: A new instance of `SiteCollectionDirectory`.
-   */
+  /// A struct representing an Atom category.
+  ///   Creates a site collection directory from a site collection.
+  ///
+  ///   - Parameter blogs: The site collection to build the directory from.
+  ///
+  ///   - Returns: A new instance of `SiteCollectionDirectory`.
+  /// - SeeAlso: `EntryCategory`
   public func directory(fromCollection blogs: SiteCollection) -> SiteCollectionDirectory {
     SiteCollectionDirectory(blogs: blogs)
   }
@@ -22,12 +22,12 @@ public protocol SiteDirectoryBuilder {
   /// The type of site directory to build.
   associatedtype SiteDirectoryType: SiteDirectory
 
-  /**
-   Creates a site directory from a site collection.
-
-   - Parameter blogs: The site collection to build the directory from.
-
-   - Returns: A new instance of `SiteDirectoryType`.
-   */
+  /// A struct representing an Atom category.
+  ///   Creates a site directory from a site collection.
+  ///
+  ///   - Parameter blogs: The site collection to build the directory from.
+  ///
+  ///   - Returns: A new instance of `SiteDirectoryType`.
+  /// - SeeAlso: `EntryCategory`
   func directory(fromCollection blogs: SiteCollection) -> SiteDirectoryType
 }

Sources/SyndiKit/Formats/Blogs/SiteLanguage.swift

@@ -1,32 +1,32 @@
-/**
- A struct representing a site language.
-
- Use this struct to define the type and title of a site language.
-
- - Note: This struct is used internally and should not be directly instantiated.
-
- - Parameters:
-   - content: The content of the site language.
-
- - SeeAlso: `SiteLanguageType`
-
- - Author: Your Name
- */
+/// A struct representing an Atom category.
+/// A struct representing a site language.
+///
+/// Use this struct to define the type and title of a site language.
+///
+/// - Note: This struct is used internally and should not be directly instantiated.
+///
+/// - Parameters:
+///   - content: The content of the site language.
+///
+/// - SeeAlso: `SiteLanguageType`
+///
+/// - Author: Your Name
+/// - SeeAlso: `EntryCategory`
 public struct SiteLanguage {
   /// The type of the site language.
   public let type: SiteLanguageType
 
   /// The title of the site language.
   public let title: String
 
-  /**
-   Initializes a new `SiteLanguage` instance.
-
-   - Parameters:
-     - content: The content of the site language.
-
-   - Returns: A new `SiteLanguage` instance.
-   */
+  /// A struct representing an Atom category.
+  ///   Initializes a new `SiteLanguage` instance.
+  ///
+  ///   - Parameters:
+  ///     - content: The content of the site language.
+  ///
+  ///   - Returns: A new `SiteLanguage` instance.
+  /// - SeeAlso: `EntryCategory`
   internal init(content: SiteLanguageContent) {
     type = content.language
     title = content.title

Sources/SyndiKit/Formats/Blogs/SiteLanguageCategory.swift

@@ -1,12 +1,12 @@
-/**
- A struct representing a category of site languages.
-
- - Note: This struct conforms to the `Codable` protocol.
-
- - Important: All properties of this struct are read-only.
-
- - SeeAlso: `Site`
- */
+/// A struct representing an Atom category.
+/// A struct representing a category of site languages.
+///
+/// - Note: This struct conforms to the `Codable` protocol.
+///
+/// - Important: All properties of this struct are read-only.
+///
+/// - SeeAlso: `Site`
+/// - SeeAlso: `EntryCategory`
 public struct SiteLanguageCategory: Codable {
   /// The title of the category.
   public let title: String

Sources/SyndiKit/Formats/Blogs/SiteLanguageContent.swift

@@ -1,16 +1,16 @@
-/**
- A struct representing the content of a site in a specific language.
-
- - Note: This struct conforms to the `Codable` protocol.
-
- - Important: All properties of this struct are read-only.
-
- - SeeAlso: `SiteLanguageCategory`
-
- - Author: Your Name
-
- - Version: 1.0
- */
+/// A struct representing an Atom category.
+/// A struct representing the content of a site in a specific language.
+///
+/// - Note: This struct conforms to the `Codable` protocol.
+///
+/// - Important: All properties of this struct are read-only.
+///
+/// - SeeAlso: `SiteLanguageCategory`
+///
+/// - Author: Your Name
+///
+/// - Version: 1.0
+/// - SeeAlso: `EntryCategory`
 public struct SiteLanguageContent: Codable {
   /// The language of the site content.
   public let language: String

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

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

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

@@ -1,11 +1,11 @@
 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).
- */
+/// A struct representing an Atom category.
+/// 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).
+/// - SeeAlso: `EntryCategory`
 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,

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

@@ -1,21 +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.
-
- For more details, check out
- [the Media RSS Specification](https://www.rssboard.org/media-rss).
- */
+/// A struct representing an Atom category.
+/// 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).
+/// - SeeAlso: `EntryCategory`
 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.
-   */
+  /// A struct representing an Atom category.
+  ///   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.
+  /// - SeeAlso: `EntryCategory`
   public let url: URL
 
   /// The direct URL to the media object.

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

@@ -1,12 +1,12 @@
 import Foundation
 
-/**
- A struct representing a JSON feed.
-
- - Note: This struct conforms to the `DecodableFeed` protocol.
-
- - SeeAlso: `DecodableFeed`
- */
+/// A struct representing an Atom category.
+/// A struct representing a JSON feed.
+///
+/// - Note: This struct conforms to the `DecodableFeed` protocol.
+///
+/// - SeeAlso: `DecodableFeed`
+/// - SeeAlso: `EntryCategory`
 public struct JSONFeed {
   /// The version of the JSON feed.
   public let version: URL