Synchronizing API and documentation updates

src/main/java/org/gitnex/tea4j/v2/apis/AdminApi.java

@@ -28,7 +28,7 @@ public interface AdminApi {
   /**
    * Add a badge to a user
    *
-   * @param username username of user (required)
+   * @param username username of the user to whom a badge is to be added (required)
    * @param body (optional)
    * @return Call<Void>
    */
@@ -62,7 +62,7 @@ public interface AdminApi {
    * Create an organization
    *
    * @param body (required)
-   * @param username username of the user that will own the created organization (required)
+   * @param username username of the user who will own the created organization (required)
    * @return Call<Organization>
    */
   @Headers({"Content-Type:application/json"})
@@ -73,7 +73,7 @@ public interface AdminApi {
   /**
    * Add a public key on behalf of a user
    *
-   * @param username username of the user (required)
+   * @param username username of the user who is to receive a public key (required)
    * @param body (optional)
    * @return Call<PublicKey>
    */
@@ -86,7 +86,7 @@ public interface AdminApi {
    * Create a repository on behalf of a user
    *
    * @param body (required)
-   * @param username username of the user. This user will own the created repository (required)
+   * @param username username of the user who will own the created repository (required)
    * @return Call<Repository>
    */
   @Headers({"Content-Type:application/json"})
@@ -155,7 +155,7 @@ public interface AdminApi {
   /**
    * Delete a user
    *
-   * @param username username of user to delete (required)
+   * @param username username of the user to delete (required)
    * @param purge purge the user from the system completely (optional)
    * @return Call<Void>
    */
@@ -167,7 +167,7 @@ public interface AdminApi {
   /**
    * Remove a badge from a user
    *
-   * @param username username of user (required)
+   * @param username username of the user whose badge is to be deleted (required)
    * @param body (optional)
    * @return Call<Void>
    */
@@ -179,7 +179,7 @@ public interface AdminApi {
   /**
    * Delete a user's public key
    *
-   * @param username username of user (required)
+   * @param username username of the user whose public key is to be deleted (required)
    * @param id id of the key to delete (required)
    * @return Call<Void>
    */
@@ -202,7 +202,7 @@ public interface AdminApi {
   /**
    * Edit an existing user
    *
-   * @param username username of user to edit (required)
+   * @param username username of the user whose data is to be edited (required)
    * @param body (optional)
    * @return Call<User>
    */
@@ -267,7 +267,7 @@ public interface AdminApi {
   /**
    * List a user's badges
    *
-   * @param username username of user (required)
+   * @param username username of the user whose badges are to be listed (required)
    * @return Call<List<Badge>>
    */
   @GET("admin/users/{username}/badges")
@@ -277,7 +277,7 @@ public interface AdminApi {
    * Rename a user
    *
    * @param body (required)
-   * @param username existing username of user (required)
+   * @param username current username of the user (required)
    * @return Call<Void>
    */
   @Headers({"Content-Type:application/json"})
@@ -303,7 +303,7 @@ public interface AdminApi {
    * Search users according filter conditions
    *
    * @param sourceId ID of the user's login source to search for (optional)
-   * @param loginName user's login name to search for (optional)
+   * @param loginName identifier of the user, provided by the external authenticator (optional)
    * @param page page number of results to return (1-based) (optional)
    * @param limit page size of results (optional)
    * @return Call<List<User>>

src/main/java/org/gitnex/tea4j/v2/apis/IssueApi.java

@@ -57,7 +57,7 @@ public interface IssueApi {
    * @param owner owner of the repo (required)
    * @param repo name of the repo (required)
    * @param index index of the issue (required)
-   * @param user user to subscribe (required)
+   * @param user username of the user to subscribe the issue to (required)
    * @return Call<Void>
    */
   @PUT("repos/{owner}/{repo}/issues/{index}/subscriptions/{user}")
@@ -405,7 +405,7 @@ public interface IssueApi {
    * @param owner owner of the repo (required)
    * @param repo name of the repo (required)
    * @param index index of the issue (required)
-   * @param user user witch unsubscribe (required)
+   * @param user username of the user to unsubscribe from an issue (required)
    * @return Call<Void>
    */
   @DELETE("repos/{owner}/{repo}/issues/{index}/subscriptions/{user}")

src/main/java/org/gitnex/tea4j/v2/apis/OrganizationApi.java

@@ -199,7 +199,7 @@ public interface OrganizationApi {
    * Add a team member
    *
    * @param id id of the team (required)
-   * @param username username of the user to add (required)
+   * @param username username of the user to add to a team (required)
    * @return Call<Void>
    */
   @PUT("teams/{id}/members/{username}")
@@ -224,7 +224,7 @@ public interface OrganizationApi {
    * Conceal a user's membership
    *
    * @param org name of the organization (required)
-   * @param username username of the user (required)
+   * @param username username of the user whose membership is to be concealed (required)
    * @return Call<Void>
    */
   @DELETE("orgs/{org}/public_members/{username}")
@@ -330,7 +330,7 @@ public interface OrganizationApi {
    * Remove a member from an organization
    *
    * @param org name of the organization (required)
-   * @param username username of the user (required)
+   * @param username username of the user to remove from the organization (required)
    * @return Call<Void>
    */
   @DELETE("orgs/{org}/members/{username}")
@@ -462,7 +462,7 @@ public interface OrganizationApi {
   /**
    * Get user permissions in organization
    *
-   * @param username username of user (required)
+   * @param username username of the user whose permissions are to be obtained (required)
    * @param org name of the organization (required)
    * @return Call<OrganizationPermissions>
    */
@@ -474,7 +474,7 @@ public interface OrganizationApi {
    * Check if a user is a member of an organization
    *
    * @param org name of the organization (required)
-   * @param username username of the user (required)
+   * @param username username of the user to check for an organization membership (required)
    * @return Call<Void>
    */
   @GET("orgs/{org}/members/{username}")
@@ -485,7 +485,7 @@ public interface OrganizationApi {
    * Check if a user is a public member of an organization
    *
    * @param org name of the organization (required)
-   * @param username username of the user (required)
+   * @param username username of the user to check for a public organization membership (required)
    * @return Call<Void>
    */
   @GET("orgs/{org}/public_members/{username}")
@@ -623,7 +623,7 @@ public interface OrganizationApi {
    * List a particular member of team
    *
    * @param id id of the team (required)
-   * @param username username of the member to list (required)
+   * @param username username of the user whose data is to be listed (required)
    * @return Call<User>
    */
   @GET("teams/{id}/members/{username}")
@@ -689,7 +689,7 @@ public interface OrganizationApi {
   /**
    * List a user's organizations
    *
-   * @param username username of user (required)
+   * @param username username of the user whose organizations are to be listed (required)
    * @param page page number of results to return (1-based) (optional)
    * @param limit page size of results (optional)
    * @return Call<List<Organization>>
@@ -704,7 +704,7 @@ public interface OrganizationApi {
    * Publicize a user's membership
    *
    * @param org name of the organization (required)
-   * @param username username of the user (required)
+   * @param username username of the user whose membership is to be publicized (required)
    * @return Call<Void>
    */
   @PUT("orgs/{org}/public_members/{username}")
@@ -715,7 +715,7 @@ public interface OrganizationApi {
    * Remove a team member
    *
    * @param id id of the team (required)
-   * @param username username of the user to remove (required)
+   * @param username username of the user to remove from a team (required)
    * @return Call<Void>
    */
   @DELETE("teams/{id}/members/{username}")
@@ -753,7 +753,7 @@ public interface OrganizationApi {
    * Block a user
    *
    * @param org name of the organization (required)
-   * @param username user to block (required)
+   * @param username username of the user to block (required)
    * @param note optional note for the block (optional)
    * @return Call<Void>
    */
@@ -767,7 +767,7 @@ public interface OrganizationApi {
    * Check if a user is blocked by the organization
    *
    * @param org name of the organization (required)
-   * @param username user to check (required)
+   * @param username username of the user to check (required)
    * @return Call<Void>
    */
   @GET("orgs/{org}/blocks/{username}")
@@ -792,7 +792,7 @@ public interface OrganizationApi {
    * Unblock a user
    *
    * @param org name of the organization (required)
-   * @param username user to unblock (required)
+   * @param username username of the user to unblock (required)
    * @return Call<Void>
    */
   @DELETE("orgs/{org}/blocks/{username}")

src/main/java/org/gitnex/tea4j/v2/apis/RepositoryApi.java

@@ -639,7 +639,7 @@ public interface RepositoryApi {
    *
    * @param owner owner of the repo (required)
    * @param repo name of the repo (required)
-   * @param collaborator username of the collaborator to add (required)
+   * @param collaborator username of the user to add or update as a collaborator (required)
    * @param body (optional)
    * @return Call<Void>
    */
@@ -743,7 +743,7 @@ public interface RepositoryApi {
    *
    * @param owner owner of the repo (required)
    * @param repo name of the repo (required)
-   * @param collaborator username of the collaborator (required)
+   * @param collaborator username of the user to check for being a collaborator (required)
    * @return Call<Void>
    */
   @GET("repos/{owner}/{repo}/collaborators/{collaborator}")
@@ -2109,7 +2109,8 @@ public interface RepositoryApi {
    *
    * @param owner owner of the repo (required)
    * @param repo name of the repo (required)
-   * @param collaborator username of the collaborator (required)
+   * @param collaborator username of the collaborator whose permissions are to be obtained
+   *     (required)
    * @return Call<RepoCollaboratorPermission>
    */
   @GET("repos/{owner}/{repo}/collaborators/{collaborator}/permission")
@@ -3082,7 +3083,7 @@ public interface RepositoryApi {
    *
    * @param owner owner of the repo (required)
    * @param repo name of the repo (required)
-   * @param user username of user (required)
+   * @param user username of the user whose tracked times are to be listed (required)
    * @return Call<List<TrackedTime>>
    */
   @GET("repos/{owner}/{repo}/times/{user}")

src/main/java/org/gitnex/tea4j/v2/apis/UserApi.java

@@ -229,7 +229,7 @@ public interface UserApi {
   /**
    * Block a user
    *
-   * @param username user to block (required)
+   * @param username username of the user to block (required)
    * @param note optional note for the block (optional)
    * @return Call<Void>
    */
@@ -240,8 +240,8 @@ public interface UserApi {
   /**
    * Check if one user is following another user
    *
-   * @param username username of following user (required)
-   * @param target username of followed user (required)
+   * @param username username of the following user (required)
+   * @param target username of the followed user (required)
    * @return Call<Void>
    */
   @GET("users/{username}/following/{target}")
@@ -252,7 +252,7 @@ public interface UserApi {
   /**
    * Check if a user is blocked by the authenticated user
    *
-   * @param username user to check (required)
+   * @param username username of the user to check (required)
    * @return Call<Void>
    */
   @GET("user/blocks/{username}")
@@ -290,7 +290,7 @@ public interface UserApi {
   /**
    * Create an access token
    *
-   * @param username username of user (required)
+   * @param username username of the user whose token is to be created (required)
    * @param body (optional)
    * @return Call<AccessToken>
    */
@@ -303,7 +303,7 @@ public interface UserApi {
   /**
    * Check whether a user is followed by the authenticated user
    *
-   * @param username username of followed user (required)
+   * @param username username of the user to check for authenticated followers (required)
    * @return Call<Void>
    */
   @GET("user/following/{username}")
@@ -323,7 +323,7 @@ public interface UserApi {
   /**
    * Unfollow a user
    *
-   * @param username username of user to unfollow (required)
+   * @param username username of the user to unfollow (required)
    * @return Call<Void>
    */
   @DELETE("user/following/{username}")
@@ -479,7 +479,7 @@ public interface UserApi {
   /**
    * Follow a user
    *
-   * @param username username of user to follow (required)
+   * @param username username of the user to follow (required)
    * @return Call<Void>
    */
   @PUT("user/following/{username}")
@@ -517,7 +517,7 @@ public interface UserApi {
   /**
    * delete an access token
    *
-   * @param username username of user (required)
+   * @param username username of the user whose token is to be deleted (required)
    * @param token token to be deleted, identified by ID and if not available by name (required)
    * @return Call<Void>
    */
@@ -576,7 +576,7 @@ public interface UserApi {
   /**
    * Get a user
    *
-   * @param username username of user to get (required)
+   * @param username username of the user whose data is to be listed (required)
    * @return Call<User>
    */
   @GET("users/{username}")
@@ -593,7 +593,7 @@ public interface UserApi {
   /**
    * Get a user's heatmap
    *
-   * @param username username of user to get (required)
+   * @param username username of the user whose heatmap is to be obtained (required)
    * @return Call<List<UserHeatmapData>>
    */
   @GET("users/{username}/heatmap")
@@ -650,7 +650,7 @@ public interface UserApi {
   /**
    * List the authenticated user's access tokens
    *
-   * @param username username of user (required)
+   * @param username username of to user whose access tokens are to be listed (required)
    * @param page page number of results to return (1-based) (optional)
    * @param limit page size of results (optional)
    * @return Call<List<AccessToken>>
@@ -664,7 +664,7 @@ public interface UserApi {
   /**
    * List a user's activity feeds
    *
-   * @param username username of user (required)
+   * @param username username of the user whose activity feeds are to be listed (required)
    * @param onlyPerformedBy if true, only show actions performed by the requested user (optional)
    * @param date the date of the activities to be found (optional)
    * @param page page number of results to return (1-based) (optional)
@@ -701,7 +701,7 @@ public interface UserApi {
   /**
    * List the given user's followers
    *
-   * @param username username of user (required)
+   * @param username username of the user whose followers are to be listed (required)
    * @param page page number of results to return (1-based) (optional)
    * @param limit page size of results (optional)
    * @return Call<List<User>>
@@ -715,7 +715,7 @@ public interface UserApi {
   /**
    * List the users that the given user is following
    *
-   * @param username username of user (required)
+   * @param username username of the user whose followed users are to be listed (required)
    * @param page page number of results to return (1-based) (optional)
    * @param limit page size of results (optional)
    * @return Call<List<User>>
@@ -729,7 +729,7 @@ public interface UserApi {
   /**
    * List the given user's GPG keys
    *
-   * @param username username of user (required)
+   * @param username username of the user whose GPG key list is to be obtained (required)
    * @param page page number of results to return (1-based) (optional)
    * @param limit page size of results (optional)
    * @return Call<List<GPGKey>>
@@ -754,7 +754,7 @@ public interface UserApi {
   /**
    * List the given user's public keys
    *
-   * @param username username of user (required)
+   * @param username username of the user whose public keys are to be listed (required)
    * @param fingerprint fingerprint of the key (optional)
    * @param page page number of results to return (1-based) (optional)
    * @param limit page size of results (optional)
@@ -770,7 +770,7 @@ public interface UserApi {
   /**
    * List the repos owned by the given user
    *
-   * @param username username of user (required)
+   * @param username username of the user whose owned repos are to be listed (required)
    * @param page page number of results to return (1-based) (optional)
    * @param limit page size of results (optional)
    * @return Call<List<Repository>>
@@ -784,7 +784,7 @@ public interface UserApi {
   /**
    * The repos that the given user has starred
    *
-   * @param username username of user (required)
+   * @param username username of the user whose starred repos are to be listed (required)
    * @param page page number of results to return (1-based) (optional)
    * @param limit page size of results (optional)
    * @return Call<List<Repository>>
@@ -798,7 +798,7 @@ public interface UserApi {
   /**
    * List the repositories watched by a user
    *
-   * @param username username of the user (required)
+   * @param username username of the user whose watched repos are to be listed (required)
    * @param page page number of results to return (1-based) (optional)
    * @param limit page size of results (optional)
    * @return Call<List<Repository>>
@@ -839,7 +839,7 @@ public interface UserApi {
   /**
    * Unblock a user
    *
-   * @param username user to unblock (required)
+   * @param username username of the user to unblock (required)
    * @return Call<Void>
    */
   @DELETE("user/blocks/{username}")

src/main/java/org/gitnex/tea4j/v2/models/AddTimeOption.java

@@ -76,11 +76,11 @@ public class AddTimeOption implements Serializable {
   }
 
   /**
-   * User who spent the time (optional)
+   * username of the user who spent the time working on the issue (optional)
    *
    * @return userName
    */
-  @Schema(description = "User who spent the time (optional)")
+  @Schema(description = "username of the user who spent the time working on the issue (optional)")
   public String getUserName() {
     return userName;
   }

src/main/java/org/gitnex/tea4j/v2/models/CreateOrgOption.java

@@ -200,11 +200,11 @@ public class CreateOrgOption implements Serializable {
   }
 
   /**
-   * Get username
+   * username of the organization
    *
    * @return username
    */
-  @Schema(required = true, description = "")
+  @Schema(required = true, description = "username of the organization")
   public String getUsername() {
     return username;
   }

src/main/java/org/gitnex/tea4j/v2/models/CreateUserOption.java

@@ -33,7 +33,7 @@ public class CreateUserOption implements Serializable {
   private String fullName = null;
 
   @SerializedName("login_name")
-  private String loginName = null;
+  private String loginName = "empty";
 
   @SerializedName("must_change_password")
   private Boolean mustChangePassword = null;
@@ -124,11 +124,13 @@ public class CreateUserOption implements Serializable {
   }
 
   /**
-   * Get loginName
+   * identifier of the user, provided by the external authenticator (if configured)
    *
    * @return loginName
    */
-  @Schema(description = "")
+  @Schema(
+      description =
+          "identifier of the user, provided by the external authenticator (if configured)")
   public String getLoginName() {
     return loginName;
   }
@@ -238,11 +240,11 @@ public class CreateUserOption implements Serializable {
   }
 
   /**
-   * Get username
+   * username of the user
    *
    * @return username
    */
-  @Schema(required = true, description = "")
+  @Schema(required = true, description = "username of the user")
   public String getUsername() {
     return username;
   }

src/main/java/org/gitnex/tea4j/v2/models/EditUserOption.java

@@ -50,7 +50,7 @@ public class EditUserOption implements Serializable {
   private String location = null;
 
   @SerializedName("login_name")
-  private String loginName = null;
+  private String loginName = "empty";
 
   @SerializedName("max_repo_creation")
   private Long maxRepoCreation = null;
@@ -253,11 +253,14 @@ public class EditUserOption implements Serializable {
   }
 
   /**
-   * Get loginName
+   * identifier of the user, provided by the external authenticator (if configured)
    *
    * @return loginName
    */
-  @Schema(required = true, description = "")
+  @Schema(
+      required = true,
+      description =
+          "identifier of the user, provided by the external authenticator (if configured)")
   public String getLoginName() {
     return loginName;
   }

src/main/java/org/gitnex/tea4j/v2/models/Email.java

@@ -100,11 +100,11 @@ public class Email implements Serializable {
   }
 
   /**
-   * Get username
+   * username of the user
    *
    * @return username
    */
-  @Schema(description = "")
+  @Schema(description = "username of the user")
   public String getUsername() {
     return username;
   }

src/main/java/org/gitnex/tea4j/v2/models/Organization.java

@@ -213,11 +213,11 @@ public class Organization implements Serializable {
   }
 
   /**
-   * deprecated
+   * username of the organization deprecated
    *
    * @return username
    */
-  @Schema(description = "deprecated")
+  @Schema(description = "username of the organization deprecated")
   public String getUsername() {
     return username;
   }

src/main/java/org/gitnex/tea4j/v2/models/PayloadUser.java

@@ -75,11 +75,11 @@ public class PayloadUser implements Serializable {
   }
 
   /**
-   * Get username
+   * username of the user
    *
    * @return username
    */
-  @Schema(description = "")
+  @Schema(description = "username of the user")
   public String getUsername() {
     return username;
   }

src/main/java/org/gitnex/tea4j/v2/models/TrackedTime.java

@@ -164,11 +164,11 @@ public class TrackedTime implements Serializable {
   }
 
   /**
-   * Get userName
+   * username of the user
    *
    * @return userName
    */
-  @Schema(description = "")
+  @Schema(description = "username of the user")
   public String getUserName() {
     return userName;
   }

src/main/java/org/gitnex/tea4j/v2/models/User.java

@@ -361,11 +361,11 @@ public class User implements Serializable {
   }
 
   /**
-   * the user's username
+   * login of the user, same as `username`
    *
    * @return login
    */
-  @Schema(description = "the user's username")
+  @Schema(description = "login of the user, same as `username`")
   public String getLogin() {
     return login;
   }
@@ -380,11 +380,13 @@ public class User implements Serializable {
   }
 
   /**
-   * the user's authentication sign-in name.
+   * identifier of the user, provided by the external authenticator (if configured)
    *
    * @return loginName
    */
-  @Schema(description = "the user's authentication sign-in name.")
+  @Schema(
+      description =
+          "identifier of the user, provided by the external authenticator (if configured)")
   public String getLoginName() {
     return loginName;
   }