Add documentation for optional User.ID methods

Author: daneden

Sources/Twift+Blocks.swift

@@ -45,7 +45,7 @@ extension Twift {
   ///
   /// Equivalent to `POST /2/users/:id/blocking`
   /// - Parameters:
-  ///   - sourceUserId: The user ID who you would like to initiate the block on behalf of. It must match the user ID of the currently authenticated user.
+  ///   - sourceUserId: The user ID who you would like to initiate the block on behalf of. It must match the user ID of the currently authenticated user. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - targetUserId: The user ID of the user you would like the source user to block.
   /// - Returns: A ``BlockResponse`` indicating the blocked status.
   public func blockUser(sourceUserId: User.ID? = nil, targetUserId: User.ID) async throws -> TwitterAPIData<BlockResponse> {

Sources/Twift+Follows.swift

@@ -14,7 +14,7 @@ extension Twift {
   ///
   /// Equivalent to `GET /2/users/:id/following`.
   /// - Parameters:
-  ///   - userId: The user ID whose following you would like to retreive.
+  ///   - userId: The user ID whose following you would like to retreive. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - fields: Any additional fields to include on returned objects
   ///   - expansions: Objects and their corresponding fields that should be expanded in the `includes` property
   ///   - paginationToken: When iterating over pages of results, you can pass in the `nextToken` from the previously-returned value to get the next page of results
@@ -51,7 +51,7 @@ extension Twift {
   ///
   /// Equivalent to `GET /2/users/:id/followers`.
   /// - Parameters:
-  ///   - userId: The user ID whose followers you would like to retrieve
+  ///   - userId: The user ID whose followers you would like to retrieve. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - fields: Any additional fields to include on returned objects
   ///   - expansions: Objects and their corresponding fields that should be expanded in the `includes` property
   ///   - paginationToken: When iterating over pages of results, you can pass in the `nextToken` from the previously-returned value to get the next page of results
@@ -93,7 +93,7 @@ extension Twift {
   ///
   /// The request succeeds with no action when the authenticated user sends a request to a user they're already following, or if they're sending a follower request to a user that does not have public Tweets.
   /// - Parameters:
-  ///   - sourceUserId: The authenticated user ID who you would like to initiate the follow on behalf of.
+  ///   - sourceUserId: The authenticated user ID who you would like to initiate the follow on behalf of. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - targetUserId: The user ID of the user that you would like the `sourceUserId` to follow.
   /// - Returns: A ``FollowResponse`` indicating whether the source user is now following the target user, and whether the follow request is pending
   public func followUser(
@@ -115,7 +115,7 @@ extension Twift {
   ///
   /// The request succeeds with no action when the authenticated user sends a request to a user they're not following or have already unfollowed.
   /// - Parameters:
-  ///   - sourceUserId: The authenticated user ID who you would like to initiate the unfollow on behalf of.
+  ///   - sourceUserId: The authenticated user ID who you would like to initiate the unfollow on behalf of. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - targetUserId: The user ID of the user that you would like the `sourceUserId` to unfollow.
   /// - Returns: A ``FollowResponse`` indicating whether the source user is now following the target user
   public func unfollowUser(sourceUserId: User.ID? = nil,

Sources/Twift+Likes.swift

@@ -6,7 +6,7 @@ extension Twift {
   /// Equivalent to `POST /2/users/:user_id/likes`
   /// - Parameters:
   ///   - tweetId: The ID of the Tweet that you would like the `userId` to Like.
-  ///   - userId: The user ID who you are liking a Tweet on behalf of. It must match your own user ID or that of an authenticating user.
+  ///   - userId: The user ID who you are liking a Tweet on behalf of. It must match your own user ID or that of an authenticating user. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   /// - Returns: A response object containing a ``LikeResponse``
   public func likeTweet(_ tweetId: Tweet.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<LikeResponse> {
     guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
@@ -25,7 +25,7 @@ extension Twift {
   /// Equivalent to `DELETE /2/users/:user_id/likes/:tweet_id`
   /// - Parameters:
   ///   - tweetId: The ID of the Tweet that you would like the `userId` to unlike.
-  ///   - userId: The user ID who you are removing Like of a Tweet on behalf of. It must match your own user ID or that of an authenticating user.
+  ///   - userId: The user ID who you are removing Like of a Tweet on behalf of. It must match your own user ID or that of an authenticating user. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   /// - Returns: A response object containing a ``LikeResponse``
   public func unlikeTweet(_ tweetId: Tweet.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<LikeResponse> {
     guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
@@ -59,7 +59,7 @@ extension Twift {
   ///
   /// Equivalent to `GET /2/users/:id/liked_tweets`
   /// - Parameters:
-  ///   - userId: User ID of the user to request liked Tweets for.
+  ///   - userId: User ID of the user to request liked Tweets for. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - fields: Any additional fields to include on returned objects
   ///   - expansions: Objects and their corresponding fields that should be expanded in the `includes` property
   ///   - paginationToken: This parameter is used to move forwards or backwards through 'pages' of results, based on the value of the next_token or previous_token in the response.

Sources/Twift+Lists.swift

@@ -62,7 +62,7 @@ extension Twift {
   ///
   /// Equivalent to `GET /2/user/:user_id/owned_lists`
   /// - Parameters:
-  ///   - userId: The user ID whose owned Lists you would like to retrieve.
+  ///   - userId: The user ID whose owned Lists you would like to retrieve. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - fields: Any additional fields to include on returned objects
   ///   - expansions: Objects and their corresponding fields that should be expanded in the `includes` property
   ///   - paginationToken: When iterating over pages of results, you can pass in the `nextToken` from the previously-returned value to get the next page of results
@@ -112,7 +112,7 @@ extension Twift {
   ///
   /// Equivalent to `GET /2/user/:user_id/list_memberships`
   /// - Parameters:
-  ///   - userId: The user ID whose List memberships you would like to retrieve
+  ///   - userId: The user ID whose List memberships you would like to retrieve. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - fields: Any additional fields to include on returned objects
   ///   - expansions: Objects and their corresponding fields that should be expanded in the `includes` property
   ///   - paginationToken: When iterating over pages of results, you can pass in the `nextToken` from the previously-returned value to get the next page of results
@@ -218,7 +218,7 @@ extension Twift {
   /// Enables the authenticated user to unfollow a List.
   /// - Parameters:
   ///   - listId: The ID of the List that you would like the user id to unfollow.
-  ///   - userId: The user ID who you are unfollowing a List on behalf of. It must match your own user ID or that of an authenticating user
+  ///   - userId: The user ID who you are unfollowing a List on behalf of. It must match your own user ID or that of an authenticating user. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   /// - Returns: A response object containing the result of the unfollow request
   public func unfollowList(_ listId: List.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<FollowResponse> {
     guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
@@ -231,7 +231,7 @@ extension Twift {
   /// Enables the authenticated user to follow a List.
   /// - Parameters:
   ///   - listId: The ID of the List that you would like the user id to follow.
-  ///   - userId: The user ID who you are following a List on behalf of. It must match your own user ID or that of an authenticating user
+  ///   - userId: The user ID who you are following a List on behalf of. It must match your own user ID or that of an authenticating user. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   /// - Returns: A response object containing the result of the follow request
   public func followList(_ listId: List.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<FollowResponse> {
     guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
@@ -277,7 +277,7 @@ extension Twift {
 
   /// Returns all Lists a specified user follows.
   /// - Parameters:
-  ///   - userId: The user ID whose followed Lists you would like to retrieve.
+  ///   - userId: The user ID whose followed Lists you would like to retrieve. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - fields: Any additional fields to include on returned objects
   ///   - expansions: Objects and their corresponding fields that should be expanded in the `includes` property
   ///   - paginationToken: When iterating over pages of results, you can pass in the `nextToken` from the previously-returned value to get the next page of results
@@ -319,7 +319,7 @@ extension Twift {
   /// Equivalent to `POST /2/users/:user_id/pinned_lists`
   /// - Parameters:
   ///   - listId: The ID of the List that you would like the user id to pin.
-  ///   - userId: The user ID who you are pinning a List on behalf of. It must match your own user ID or that of an authenticating user
+  ///   - userId: The user ID who you are pinning a List on behalf of. It must match your own user ID or that of an authenticating user. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   /// - Returns: A response object containing the result of this pin list request
   public func pinList(_ listId: List.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<PinnedResponse> {
     guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
@@ -337,7 +337,7 @@ extension Twift {
   /// Equivalent to `DELETE /2/users/:user_id/pinned_lists/:list_id`
   /// - Parameters:
   ///   - listId: The ID of the List that you would like the user id to unpin.
-  ///   - userId: The user ID who you are unpinning a List on behalf of. It must match your own user ID or that of an authenticating user
+  ///   - userId: The user ID who you are unpinning a List on behalf of. It must match your own user ID or that of an authenticating user. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   /// - Returns: A response object containing the result of this unpin list request
   public func unpinList(_ listId: List.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<PinnedResponse> {
     guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
@@ -349,7 +349,7 @@ extension Twift {
 
   /// Returns all Lists a specified user has pinned.
   /// - Parameters:
-  ///   - userId: The user ID whose pinned Lists you would like to retrieve.
+  ///   - userId: The user ID whose pinned Lists you would like to retrieve. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - fields: Any additional fields to include on returned objects
   ///   - expansions: Objects and their corresponding fields that should be expanded in the `includes` property
   /// - Returns: A response object containing an array of lists pinned by the user, any requested expansions, and a meta object with pagination information

Sources/Twift+Mutes.swift

@@ -7,7 +7,7 @@ extension Twift {
   ///
   /// Equivalent to `GET /2/users/:id/muting`.
   /// - Parameters:
-  ///   - userId: The user ID whose muted users you would like to retrieve
+  ///   - userId: The user ID whose muted users you would like to retrieve. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - fields: Any additional fields to include on returned objects
   ///   - expansions: Objects and their corresponding fields that should be expanded in the `includes` property
   ///   - paginationToken: When iterating over pages of results, you can pass in the `nextToken` from the previously-returned value to get the next page of results
@@ -44,7 +44,7 @@ extension Twift {
   ///
   /// Equivalent to `POST /2/users/:id/muting`
   /// - Parameters:
-  ///   - sourceUserId: The user ID who you would like to initiate the mute on behalf of. It must match the user ID of the currently authenticated user.
+  ///   - sourceUserId: The user ID who you would like to initiate the mute on behalf of. It must match the user ID of the currently authenticated user. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - targetUserId: The user ID of the user you would like the source user to mute.
   /// - Returns: A ``MuteResponse`` indicating the muted status.
   public func muteUser(sourceUserId: User.ID? = nil, targetUserId: User.ID) async throws -> TwitterAPIData<MuteResponse> {
@@ -62,7 +62,7 @@ extension Twift {
   ///
   /// Equivalent to `DELETE /2/users/:source_user_id/muting/:target_user_id`
   /// - Parameters:
-  ///   - sourceUserId: The user ID who you would like to initiate the mute on behalf of. It must match the user ID of the currently authenticated user.
+  ///   - sourceUserId: The user ID who you would like to initiate the mute on behalf of. It must match the user ID of the currently authenticated user. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - targetUserId: The user ID of the user you would like the source user to mute.
   /// - Returns: A ``MuteResponse`` indicating the muted status.
   public func unmuteUser(sourceUserId: User.ID? = nil, targetUserId: User.ID) async throws -> TwitterAPIData<MuteResponse> {

Sources/Twift+Retweets.swift

@@ -6,7 +6,7 @@ extension Twift {
   /// Equivalent to `POST /2/users/:user_id/retweets`
   /// - Parameters:
   ///   - tweetId: The ID of the Tweet that you would like the `userId` to Retweet.
-  ///   - userId: The user ID who you are Retweeting a Tweet on behalf of. It must match your own user ID or that of an authenticating user.
+  ///   - userId: The user ID who you are Retweeting a Tweet on behalf of. It must match your own user ID or that of an authenticating user. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   /// - Returns: A response object containing the result of the request
   public func retweet(_ tweetId: Tweet.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<RetweetResponse> {
     guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }
@@ -25,7 +25,7 @@ extension Twift {
   /// Equivalent to `DELETE /2/users/:user_id/retweets/:tweet_id`
   /// - Parameters:
   ///   - tweetId: The ID of the Tweet that you would like the `userId` to remove the Retweet of.
-  ///   - userId: The user ID who you are removing a the Retweet of a Tweet on behalf of. It must match your own user ID or that of an authenticating user.
+  ///   - userId: The user ID who you are removing a the Retweet of a Tweet on behalf of. It must match your own user ID or that of an authenticating user. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   /// - Returns: A response object containing the result of the request
   public func unretweet(_ tweetId: Tweet.ID, userId: User.ID? = nil) async throws -> TwitterAPIData<RetweetResponse> {
     guard let userId = userId ?? authenticatedUserId else { throw TwiftError.MissingUserID }

Sources/Twift+Tweets.swift

@@ -46,7 +46,7 @@ extension Twift {
   ///
   /// Equivalent to `GET /2/users/:id/timeline`
   /// - Parameters:
-  ///   - userId: Unique identifier of the Twitter account (user ID) for whom to return results.
+  ///   - userId: Unique identifier of the Twitter account (user ID) for whom to return results. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - startTime: The oldest or earliest UTC timestamp from which the Tweets will be provided. Only the 3200 most recent Tweets are available. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). Minimum allowable time is 2010-11-06T00:00:00Z
   ///   - endTime: The newest or most recent UTC timestamp from which the Tweets will be provided. Only the 3200 most recent Tweets are available. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). Minimum allowable time is 2010-11-06T00:00:01Z
   ///   - exclude: Comma-separated list of the types of Tweets to exclude from the response. When exclude=retweets is used, the maximum historical Tweets returned is still 3200. When the exclude=replies parameter is used for any value, only the most recent 800 Tweets are available.
@@ -95,7 +95,7 @@ extension Twift {
   ///
   /// Equivalent to `GET /2/users/:id/mentions`
   /// - Parameters:
-  ///   - userId: Unique identifier of the Twitter account (user ID) for whom to return results.
+  ///   - userId: Unique identifier of the Twitter account (user ID) for whom to return results. When set to `nil`, this method will try to use the currently-authenticated user's ID.
   ///   - startTime: The oldest or earliest UTC timestamp from which the Tweets will be provided. Only the 3200 most recent Tweets are available. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). Minimum allowable time is 2010-11-06T00:00:00Z
   ///   - endTime: The newest or most recent UTC timestamp from which the Tweets will be provided. Only the 3200 most recent Tweets are available. Timestamp is in second granularity and is inclusive (for example, 12:00:01 includes the first second of the minute). Minimum allowable time is 2010-11-06T00:00:01Z
   ///   - exclude: Comma-separated list of the types of Tweets to exclude from the response. When exclude=retweets is used, the maximum historical Tweets returned is still 3200. When the exclude=replies parameter is used for any value, only the most recent 800 Tweets are available.