refact: update doc of FavoriteServiceProtocol

Author: makinosp

Sources/VRCKit/Protocols/FavoriteServiceProtocol.swift

@@ -6,14 +6,52 @@
 //
 
 public protocol FavoriteServiceProtocol: Sendable {
+    /// Asynchronously retrieves a list of favorite groups from the server.
+    /// - Returns: An array of `FavoriteGroup` objects.
     func listFavoriteGroups() async throws -> [FavoriteGroup]
+
+    /// Lists a user's all favorites with the specified parameters.
+    /// - Parameter type: The type of favorite (e.g., friend, world).
+    /// - Returns: An array of `Favorite` objects.
     func listFavorites(type: FavoriteType) async throws -> [Favorite]
+
+    /// Lists a user's favorites with the specified parameters.
+    /// - Parameters:
+    ///   - n: The number of favorites to retrieve. Default is `60`.
+    ///   - offset: Offset value of favorites to retrive. Default is `0`.
+    ///   - type: The type of favorite (e.g., friend, world).
+    ///   - tag: An optional tag to filter favorites.
+    /// - Returns: An array of `Favorite` objects.
+    func listFavorites(n: Int, offset: Int, type: FavoriteType, tag: String?) async throws -> [Favorite]
+
+    /// Fetches details of favorite groups asynchronously.
+    /// - Parameters:
+    ///   - favoriteGroups: An array of `FavoriteGroup` objects.
+    ///   - type: The type of favorite (e.g., friend, world).
+    /// - Returns: An array of `FavoriteList` objects containing detailed information about the favorite groups.
     func fetchFavoriteList(favoriteGroups: [FavoriteGroup], type: FavoriteType) async throws -> [FavoriteList]
+
+    /// Adds a new favorite to a specific group.
+    /// - Parameters:
+    ///   - type: The type of favorite (e.g., friend, world).
+    ///   - favoriteId: The ID of the item to favorite.
+    ///   - tag: The tag to associate with the favorite.
+    /// - Returns: The newly added `Favorite` object.
     func addFavorite(type: FavoriteType, favoriteId: String, tag: String) async throws -> Favorite
+
+    /// Updates a favorite group with the given parameters, display name, and visibility.
+    /// - Parameters:
+    ///   - source: An object containing the favorite group's details.
+    ///   - displayName: The new display name to update the favorite group with.
+    ///   - visibility: The new visibility setting for the favorite group.
     func updateFavoriteGroup(
         source: FavoriteGroup,
         displayName: String,
         visibility: FavoriteGroup.Visibility
     ) async throws
+
+    /// Asynchronously remove favorite.
+    /// - Parameter favoriteId: The ID of the favorite to remove.
+    /// - Returns: A `SuccessResponse` objects.
     func removeFavorite(favoriteId: String) async throws -> SuccessResponse
 }

Sources/VRCKit/Services/FavoriteService.swift

@@ -14,17 +14,12 @@ public final actor FavoriteService: APIService, FavoriteServiceProtocol {
     private let limit = 100
     private let maxCount = 400
 
-    /// Asynchronously retrieves a list of favorite groups from the server.
-    /// - Returns: An array of `FavoriteGroup` objects.
     public func listFavoriteGroups() async throws -> [FavoriteGroup] {
         let path = "favorite/groups"
         let response = try await client.request(path: path, method: .get)
         return try Serializer.shared.decode(response.data)
     }
 
-    /// Lists a user's all favorites with the specified parameters.
-    /// - Parameter type: The type of favorite (e.g., friend, world).
-    /// - Returns: An array of `Favorite` objects.
     public func listFavorites(type: FavoriteType) async throws -> [Favorite] {
         try await withThrowingTaskGroup(of: [Favorite].self) { taskGroup in
             for offset in stride(from: .zero, to: maxCount, by: limit) {
@@ -41,13 +36,7 @@ public final actor FavoriteService: APIService, FavoriteServiceProtocol {
         }
     }
 
-    /// Lists a user's favorites with the specified parameters.
-    /// - Parameters:
-    ///   - n: The number of favorites to retrieve. Default is `60``.
-    ///   - type: The type of favorite (e.g., friend, world).
-    ///   - tag: An optional tag to filter favorites.
-    /// - Returns: An array of `Favorite` objects.
-    private func listFavorites(
+    public func listFavorites(
         n: Int = 100,
         offset: Int = 0,
         type: FavoriteType,
@@ -66,11 +55,6 @@ public final actor FavoriteService: APIService, FavoriteServiceProtocol {
         return try Serializer.shared.decode(response.data)
     }
 
-    /// Fetches details of favorite groups asynchronously.
-    /// - Parameters:
-    ///   - favoriteGroups: An array of `FavoriteGroup` objects.
-    ///   - type: The type of favorite (e.g., friend, world).
-    /// - Returns: An array of `FavoriteDetail` objects containing detailed information about the favorite groups.
     public func fetchFavoriteList(favoriteGroups: [FavoriteGroup], type: FavoriteType) async throws -> [FavoriteList] {
         try await withThrowingTaskGroup(of: FavoriteList.self) { taskGroup in
             for favoriteGroup in favoriteGroups.filter({ $0.type == type }) {
@@ -88,12 +72,6 @@ public final actor FavoriteService: APIService, FavoriteServiceProtocol {
         }
     }
 
-    /// Adds a new favorite to a specific group.
-    /// - Parameters:
-    ///   - type: The type of favorite (e.g., friend, world).
-    ///   - favoriteId: The ID of the item to favorite.
-    ///   - tag: The tag to associate with the favorite.
-    /// - Returns: The newly added `Favorite` object.
     public func addFavorite(
         type: FavoriteType,
         favoriteId: String,
@@ -107,14 +85,6 @@ public final actor FavoriteService: APIService, FavoriteServiceProtocol {
         return try Serializer.shared.decode(response.data)
     }
 
-    /// Updates a favorite group with the given parameters, display name, and visibility.
-    /// - Parameters:
-    ///   - params: A tuple containing the favorite group's details:
-    ///     - type: The type of the favorite group, defined by `FavoriteType`.
-    ///     - name: The name of the favorite group.
-    ///     - userId: The ID of the user associated with the favorite group.
-    ///   - displayName: The new display name to update the favorite group with.
-    ///   - visibility: The new visibility setting for the favorite group.
     public func updateFavoriteGroup(
         source: FavoriteGroup,
         displayName: String,
@@ -127,9 +97,6 @@ public final actor FavoriteService: APIService, FavoriteServiceProtocol {
         _ = try await client.request(path: path, method: .put, body: requestData)
     }
 
-    /// Asynchronously remove favorite.
-    /// - Parameter favoriteId: The ID of the favorite to remove.
-    /// - Returns: A `SuccessResponse` objects.
     public func removeFavorite(favoriteId: String) async throws -> SuccessResponse {
         let path = "favorites/\(favoriteId)"
         let response = try await client.request(path: path, method: .delete)