Merge pull request #115 from bocops/104_documenting_method_classes

Kdoc for most method classes

bigbone/src/main/kotlin/social/bigbone/api/method/AccountMethods.kt

@@ -14,15 +14,22 @@ import social.bigbone.api.entity.Status
  * @see <a href="https://docs.joinmastodon.org/methods/accounts/">Mastodon accounts API methods</a>
  */
 class AccountMethods(private val client: MastodonClient) {
-    // GET /api/v1/accounts/:id
+    /**
+     * View information about a profile.
+     * @param accountId ID of the profile to look up
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#get">Mastodon API documentation: methods/accounts/#get</a>
+     */
     fun getAccount(accountId: String): MastodonRequest<Account> {
         return client.getMastodonRequest(
             endpoint = "api/v1/accounts/$accountId",
             method = MastodonClient.Method.GET
         )
     }
 
-    //  GET /api/v1/accounts/verify_credentials
+    /**
+     * Test to make sure that the user token works.
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#verify_credentials">Mastodon API documentation: methods/accounts/#verify_credentials</a>
+     */
     fun verifyCredentials(): MastodonRequest<Account> {
         return client.getMastodonRequest(
             endpoint = "api/v1/accounts/verify_credentials",
@@ -31,11 +38,14 @@ class AccountMethods(private val client: MastodonClient) {
     }
 
     /**
-     * PATCH /api/v1/accounts/update_credentials
-     * display_name: The name to display in the user's profile
-     * note: A new biography for the user
-     * avatar: A base64 encoded image to display as the user's avatar (e.g. data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAADrCAYAAAA...)
-     * header: A base64 encoded image to display as the user's header image (e.g. data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAADrCAYAAAA...)
+     * Update the user’s display and preferences.
+     * @param displayName The name to display in the user's profile
+     * @param note A new biography for the user
+     * @param avatar A String containing a base64-encoded image to display as the user's avatar
+     *  (e.g. data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAADrCAYAAAA...)
+     * @param header A String containing a base64-encoded image to display as the user's header image
+     *  (e.g. data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAADrCAYAAAA...)
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#update_credentials">Mastodon API documentation: methods/accounts/#update_credentials</a>
      */
     fun updateCredentials(displayName: String?, note: String?, avatar: String?, header: String?): MastodonRequest<Account> {
         return client.getMastodonRequest(
@@ -50,7 +60,12 @@ class AccountMethods(private val client: MastodonClient) {
         )
     }
 
-    //  GET /api/v1/accounts/:id/followers
+    /**
+     * Accounts which follow the given account, if network is not hidden by the account owner.
+     * @param accountId ID of the account to look up
+     * @param range optional Range for the pageable return value
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#followers">Mastodon API documentation: methods/accounts/#followers</a>
+     */
     @JvmOverloads
     fun getFollowers(accountId: String, range: Range = Range()): MastodonRequest<Pageable<Account>> {
         return client.getPageableMastodonRequest(
@@ -60,7 +75,12 @@ class AccountMethods(private val client: MastodonClient) {
         )
     }
 
-    //  GET /api/v1/accounts/:id/following
+    /**
+     * Accounts which the given account is following, if network is not hidden by the account owner.
+     * @param accountId ID of the account to look up
+     * @param range optional Range for the pageable return value
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#following">Mastodon API documentation: methods/accounts/#following</a>
+     */
     @JvmOverloads
     fun getFollowing(accountId: String, range: Range = Range()): MastodonRequest<Pageable<Account>> {
         return client.getPageableMastodonRequest(
@@ -70,7 +90,15 @@ class AccountMethods(private val client: MastodonClient) {
         )
     }
 
-    //  GET /api/v1/accounts/:id/statuses
+    /**
+     * Statuses posted to the given account.
+     * @param accountId ID of the account to look up
+     * @param onlyMedia Filter out statuses without attachments.
+     * @param excludeReplies Filter out statuses in reply to a different account.
+     * @param pinned Filter for pinned statuses only.
+     * @param range optional Range for the pageable return value
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#statuses">Mastodon API documentation: methods/accounts/#statuses</a>
+     */
     @JvmOverloads
     fun getStatuses(
         accountId: String,
@@ -90,55 +118,83 @@ class AccountMethods(private val client: MastodonClient) {
         )
     }
 
-    //  POST /api/v1/accounts/:id/follow
+    /**
+     * Follow the given account. Can also be used to update whether to show reblogs or enable notifications.
+     * @param accountId ID of the account to follow
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#follow">Mastodon API documentation: methods/accounts/#follow</a>
+     */
     fun followAccount(accountId: String): MastodonRequest<Relationship> {
         return client.getMastodonRequest(
             endpoint = "api/v1/accounts/$accountId/follow",
             method = MastodonClient.Method.POST,
         )
     }
 
-    //  POST /api/v1/accounts/:id/unfollow
+    /**
+     * Unfollow the given account.
+     * @param accountId ID of the account to unfollow
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#unfollow">Mastodon API documentation: methods/accounts/#unfollow</a>
+     */
     fun unfollowAccount(accountId: String): MastodonRequest<Relationship> {
         return client.getMastodonRequest(
             endpoint = "api/v1/accounts/$accountId/unfollow",
             method = MastodonClient.Method.POST
         )
     }
 
-    //  POST /api/v1/accounts/:id/block
+    /**
+     * Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)
+     * @param accountId ID of the account to block
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#block">Mastodon API documentation: methods/accounts/#block</a>
+     */
     fun blockAccount(accountId: String): MastodonRequest<Relationship> {
         return client.getMastodonRequest(
             endpoint = "api/v1/accounts/$accountId/block",
             method = MastodonClient.Method.POST
         )
     }
 
-    //  POST /api/v1/accounts/:id/unblock
+    /**
+     * Unblock the given account.
+     * @param accountId ID of the account to unblock
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#unblock">Mastodon API documentation: methods/accounts/#unblock</a>
+     */
     fun unblockAccount(accountId: String): MastodonRequest<Relationship> {
         return client.getMastodonRequest(
             endpoint = "api/v1/accounts/$accountId/unblock",
             method = MastodonClient.Method.POST
         )
     }
 
-    //  POST /api/v1/accounts/:id/mute
+    /**
+     * Mute the given account. Clients should filter statuses and notifications from this account, if received (e.g. due to a boost in the Home timeline).
+     * @param accountId ID of the account to mute
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#mute">Mastodon API documentation: methods/accounts/#mute</a>
+     */
     fun muteAccount(accountId: String): MastodonRequest<Relationship> {
         return client.getMastodonRequest(
             endpoint = "api/v1/accounts/$accountId/mute",
             method = MastodonClient.Method.POST
         )
     }
 
-    //  POST /api/v1/accounts/:id/unmute
+    /**
+     * Unmute the given account.
+     * @param accountId ID of the account to mute
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#unmute">Mastodon API documentation: methods/accounts/#unmute</a>
+     */
     fun unmuteAccount(accountId: String): MastodonRequest<Relationship> {
         return client.getMastodonRequest(
             endpoint = "api/v1/accounts/$accountId/unmute",
             method = MastodonClient.Method.POST
         )
     }
 
-    //  GET /api/v1/accounts/relationships
+    /**
+     * Find out whether a given account is followed, blocked, muted, etc.
+     * @param accountIds List of IDs of the accounts to check
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#relationships">Mastodon API documentation: methods/accounts/#relationships</a>
+     */
     fun getRelationships(accountIds: List<String>): MastodonRequest<List<Relationship>> {
         return client.getMastodonRequestForList(
             endpoint = "api/v1/accounts/relationships",
@@ -147,11 +203,11 @@ class AccountMethods(private val client: MastodonClient) {
         )
     }
 
-    // GET /api/v1/accounts/search
     /**
-     * Performs an account search.
+     * Search for matching accounts by username or display name.
      * @param query the search query
      * @param limit the maximum number of matching accounts to return (default: 40)
+     * @see <a href="https://docs.joinmastodon.org/methods/accounts/#search">Mastodon API documentation: methods/accounts/#search</a>
      */
     @JvmOverloads
     fun searchAccounts(query: String, limit: Int = 40): MastodonRequest<List<Account>> {

bigbone/src/main/kotlin/social/bigbone/api/method/AppMethods.kt

@@ -14,7 +14,11 @@ class AppMethods(private val client: MastodonClient) {
 
     /**
      * Create a new application to obtain OAuth2 credentials.
-     *
+     * @param clientName A name for your application
+     * @param redirectUris Where the user should be redirected after authorization. Defaults to "urn:ietf:wg:oauth:2.0:oob",
+     *  which will display the authorization code to the user instead of redirecting to a web page.
+     * @param scope Space separated list of scopes. Defaults to all scopes.
+     * @param website A URL to the homepage of your app, defaults to null.
      * @see <a href="https://docs.joinmastodon.org/methods/apps/#create">Mastodon apps API methods #create</a>
      */
     @JvmOverloads

bigbone/src/main/kotlin/social/bigbone/api/method/BlockMethods.kt

@@ -12,7 +12,11 @@ import social.bigbone.api.entity.Account
  */
 class BlockMethods(private val client: MastodonClient) {
 
-    //  GET /api/v1/blocks
+    /**
+     * View your blocks. Blocking and unblocking is achieved via accounts methods.
+     * @param range optional Range for the pageable return value
+     * @see <a href="https://docs.joinmastodon.org/methods/blocks/#get">Mastodon API documentation: methods/blocks/#get</a>
+     */
     @JvmOverloads
     fun getBlocks(range: Range = Range()): MastodonRequest<Pageable<Account>> {
         return client.getPageableMastodonRequest(

bigbone/src/main/kotlin/social/bigbone/api/method/FavouriteMethods.kt

@@ -12,7 +12,11 @@ import social.bigbone.api.entity.Status
  */
 class FavouriteMethods(private val client: MastodonClient) {
 
-    //  GET /api/v1/favourites
+    /**
+     * View your favourites. Favouring and unfavouring is achieved via statuses methods.
+     * @param range optional Range for the pageable return value
+     * @see <a href="https://docs.joinmastodon.org/methods/favourites/#get">Mastodon API documentation: methods/favourites/#get</a>
+     */
     @JvmOverloads
     fun getFavourites(range: Range = Range()): MastodonRequest<Pageable<Status>> {
         return client.getPageableMastodonRequest(

bigbone/src/main/kotlin/social/bigbone/api/method/FollowRequestMethods.kt

@@ -12,7 +12,12 @@ import social.bigbone.api.exception.BigBoneRequestException
  * @see <a href="https://docs.joinmastodon.org/methods/follow_requests/">Mastodon follow_requests API methods</a>
  */
 class FollowRequestMethods(private val client: MastodonClient) {
-    // GET /api/v1/follow_requests
+
+    /**
+     * View pending follow requests.
+     * @param range optional Range for the pageable return value
+     * @see <a href="https://docs.joinmastodon.org/methods/follow_requests/#get">Mastodon API documentation: methods/follow_requests/#get</a>
+     */
     @JvmOverloads
     fun getFollowRequests(range: Range = Range()): MastodonRequest<Pageable<Account>> {
         return client.getPageableMastodonRequest(
@@ -22,7 +27,11 @@ class FollowRequestMethods(private val client: MastodonClient) {
         )
     }
 
-    //  POST /api/v1/follow_requests/:id/authorize
+    /**
+     * Accept follow request.
+     * @param accountId ID of the account whose follow request should be accepted.
+     * @see <a href="https://docs.joinmastodon.org/methods/follow_requests/#accept">Mastodon API documentation: methods/follow_requests/#accept</a>
+     */
     @Throws(BigBoneRequestException::class)
     fun authorizeFollowRequest(accountId: String) {
         client.performAction(
@@ -31,7 +40,11 @@ class FollowRequestMethods(private val client: MastodonClient) {
         )
     }
 
-    //  POST /api/v1/follow_requests/:id/reject
+    /**
+     * Reject follow request.
+     * @param accountId ID of the account whose follow request should be rejected.
+     * @see <a href="https://docs.joinmastodon.org/methods/follow_requests/#reject">Mastodon API documentation: methods/follow_requests/#reject</a>
+     */
     @Throws(BigBoneRequestException::class)
     fun rejectFollowRequest(accountId: String) {
         client.performAction(

bigbone/src/main/kotlin/social/bigbone/api/method/MediaMethods.kt

@@ -14,7 +14,7 @@ import java.io.File
  */
 class MediaMethods(private val client: MastodonClient) {
     /**
-     * Creates an attachment to be used with a new status.
+     * Creates an attachment to be used with a new status. This method will return after the full sized media is done processing.
      * @param file the file that should be uploaded
      * @param mediaType media type of the file as a string, e.g. "image/png"
      * @see <a href="https://docs.joinmastodon.org/methods/media/#v1">Mastodon API documentation: methods/media/#v1</a>

bigbone/src/main/kotlin/social/bigbone/api/method/MuteMethods.kt

@@ -11,7 +11,12 @@ import social.bigbone.api.entity.Account
  * @see <a href="https://docs.joinmastodon.org/methods/mutes/">Mastodon mutes API methods</a>
  */
 class MuteMethods(private val client: MastodonClient) {
-    // GET /api/v1/mutes
+
+    /**
+     * Accounts the user has muted.
+     * @param range optional Range for the pageable return value
+     * @see <a href="https://docs.joinmastodon.org/methods/mutes/#get">Mastodon API documentation: methods/mutes/#get</a>
+     */
     @JvmOverloads
     fun getMutes(range: Range = Range()): MastodonRequest<Pageable<Account>> {
         return client.getPageableMastodonRequest(

bigbone/src/main/kotlin/social/bigbone/api/method/NotificationMethods.kt

@@ -12,7 +12,13 @@ import social.bigbone.api.exception.BigBoneRequestException
  * @see <a href="https://docs.joinmastodon.org/methods/notifications/">Mastodon notifications API methods</a>
  */
 class NotificationMethods(private val client: MastodonClient) {
-    // GET /api/v1/notifications
+
+    /**
+     * Notifications concerning the user.
+     * @param range optional Range for the pageable return value
+     * @param excludeTypes Types to exclude from the results. See Mastodon API documentation for details.
+     * @see <a href="https://docs.joinmastodon.org/methods/notifications/#get">Mastodon API documentation: methods/notifications/#get</a>
+     */
     @JvmOverloads
     fun getNotifications(range: Range = Range(), excludeTypes: List<Notification.Type>? = null): MastodonRequest<Pageable<Notification>> {
         return client.getPageableMastodonRequest(
@@ -26,15 +32,22 @@ class NotificationMethods(private val client: MastodonClient) {
         )
     }
 
-    // GET /api/v1/notifications/:id
+    /**
+     * View information about a notification with a given ID.
+     * @param id ID of the notification to view
+     * @see <a href="https://docs.joinmastodon.org/methods/notifications/#get-one">Mastodon API documentation: methods/notifications/#get-one</a>
+     */
     fun getNotification(id: String): MastodonRequest<Notification> {
         return client.getMastodonRequest(
             endpoint = "api/v1/notification/$id", // singular "notification" is correct here
             method = MastodonClient.Method.GET
         )
     }
 
-    //  POST /api/v1/notifications/clear
+    /**
+     * Clear all notifications from the server.
+     * @see <a href="https://docs.joinmastodon.org/methods/notifications/#clear">Mastodon API documentation: methods/notifications/#clear</a>
+     */
     @Throws(BigBoneRequestException::class)
     fun clearNotifications() {
         client.performAction(

bigbone/src/main/kotlin/social/bigbone/api/method/OAuthMethods.kt

@@ -17,7 +17,11 @@ class OAuthMethods(private val client: MastodonClient) {
      * it will create and return an authorization code, then redirect to the desired redirectUri,
      * or show the authorization code if urn:ietf:wg:oauth:2.0:oob was requested.
      * The authorization code can be used while requesting a token to obtain access to user-level methods.
-     *
+     * @param clientId The client ID, obtained during app registration.
+     * @param scope List of requested OAuth scopes, separated by spaces. Must be a subset of scopes declared during app registration.
+     * @param redirectUri Set a URI to redirect the user to. Defaults to "urn:ietf:wg:oauth:2.0:oob",
+     *  which will display the authorization code to the user instead of redirecting to a web page.
+     *  Must match one of the redirect_uris declared during app registration.
      * @see <a href="https://docs.joinmastodon.org/methods/oauth/#authorize">Mastodon oauth API methods #authorize</a>
      */
     fun getOAuthUrl(clientId: String, scope: Scope, redirectUri: String = "urn:ietf:wg:oauth:2.0:oob"): String {
@@ -32,7 +36,13 @@ class OAuthMethods(private val client: MastodonClient) {
 
     /**
      * Obtain an access token, to be used during API calls that are not public.
-     *
+     * @param clientId The client ID, obtained during app registration.
+     * @param clientSecret The client secret, obtained during app registration.
+     * @param redirectUri Set a URI to redirect the user to. Defaults to "urn:ietf:wg:oauth:2.0:oob",
+     *  which will display the authorization code to the user instead of redirecting to a web page.
+     *  Must match one of the redirect_uris declared during app registration.
+     * @param code A user authorization code, obtained via the URL received from getOAuthUrl()
+     * @param grantType See Mastodon API documentation for details. Defaults to "authorization_code".
      * @see <a href="https://docs.joinmastodon.org/methods/oauth/#token">Mastodon oauth API methods #token</a>
      */
     @JvmOverloads

bigbone/src/main/kotlin/social/bigbone/api/method/ReportMethods.kt

@@ -25,10 +25,11 @@ class ReportMethods(private val client: MastodonClient) {
     }
 
     /**
-     * POST /api/v1/reports
-     * account_id: The ID of the account to report
-     * status_ids: The IDs of statuses to report (can be an array)
-     * comment: A comment to associate with the report.
+     * File a report.
+     * @param accountId The ID of the account to report
+     * @param statusId The ID of a status to report
+     * @param comment The reason for the report. Default maximum of 1000 characters.
+     * @see <a href="https://docs.joinmastodon.org/methods/reports/#post">Mastodon API documentation: methods/reports/#post</a>
      */
     @Throws(BigBoneRequestException::class)
     fun fileReport(accountId: String, statusId: String, comment: String): MastodonRequest<Report> {