make corrections and improvements to apidocs (no code changes)

website/server/controllers/api-v3/auth.js

@@ -29,7 +29,7 @@ const api = {};
 /**
  * @api {post} /api/v3/user/auth/local/register Register
  * @apiDescription Register a new user with email, login name, and password or
- * attach local auth to a social user
+ * attach local authentication to a social-auth user
  * @apiName UserRegisterLocal
  * @apiGroup User
  *
@@ -148,12 +148,14 @@ api.loginSocial = {
 
 /**
  * @api {put} /api/v3/user/auth/update-username Update username
- * @apiDescription Update the username of a local user
+ * @apiDescription Update and verify the user's username
  * @apiName UpdateUsername
  * @apiGroup User
  *
  * @apiParam (Body) {String} username The new username
-
+ * @apiParam (Body) {String} password The user's password if they use local authentication.
+ * Omit if they use social auth.
+ *
  * @apiSuccess {String} data.username The new username
  * */
 api.updateUsername = {
@@ -196,6 +198,8 @@ api.updateUsername = {
     // save username
     user.auth.local.lowerCaseUsername = newUsername.toLowerCase();
     user.auth.local.username = newUsername;
+
+    // reward user for verifying their username
     if (!user.flags.verifiedUsername) {
       user.flags.verifiedUsername = true;
       if (user.items.pets['Bear-Veteran']) {
@@ -277,7 +281,7 @@ api.updatePassword = {
 };
 
 /**
- * @api {post} /api/v3/user/reset-password Reset password
+ * @api {post} /api/v3/user/reset-password Reset password (email a reset link)
  * @apiDescription Send the user an email to let them reset their password
  * @apiName ResetPassword
  * @apiGroup User
@@ -371,7 +375,7 @@ api.updateEmail = {
 };
 
 /**
- * @api {post} /api/v3/user/auth/reset-password-set-new-one Reset Password Set New one
+ * @api {post} /api/v3/user/auth/reset-password-set-new-one Reset password (set a new one)
  * @apiDescription Set a new password for a user that reset theirs. Not meant for public usage.
  * @apiName ResetPasswordSetNewOne
  * @apiGroup User
@@ -424,8 +428,8 @@ api.resetPasswordSetNewOne = {
 
 /**
  * @api {delete} /api/v3/user/auth/social/:network Delete social authentication method
- * @apiDescription Remove a social authentication method (only facebook supported)
- * from a user profile. The user must have local authentication enabled
+ * @apiDescription Remove a social authentication method from a user profile.
+ * The user must have another authentication method enabled.
  * @apiName UserDeleteSocial
  * @apiGroup User
  *