improvements to apidocs comments (#11832)

* make corrections and improvements to apidocs (no code changes)

* make further minor tweaks to apidocs that were previously changed

* make one extra small change for consistency

* fix lines that are too long

Each line was fixed by one of these:
- changing the wording
- breaking into separate lines
- adding eslint-disable-line max-len (necessary for `@api ` lines because
a line break there causes the first part of the text to not be displayed
on the apidocs website)

* apply eslint-disable max-len around block comments that need to have a long line

The `@api ` lines can't have a line break in them because it would
cause the first part of the text to not be displayed on the apidocs
website.

Using `// eslint-disable-line max-len` at the end of an `@api `
line doesn't work, possibly because it's nesting a comment inside
a multi-line comment.

The only way I've found to ignore the `max-len` rule is to put
disable and enable comments around the whole comment block.

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)
+ * @apiDescription Remove a social authentication method from a user profile.
- * from a user profile. The user must have local authentication enabled
+ * The user must have another authentication method enabled.
  * @apiName UserDeleteSocial
  * @apiGroup User
  *

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

@@ -513,7 +513,7 @@ api.getGroupChallenges = {
 };
 
 /**
- * @api {get} /api/v3/challenges/:challengeId Get a challenge given its id
+ * @api {get} /api/v3/challenges/:challengeId Get a challenge
  * @apiName GetChallenge
  * @apiGroup Challenge
  *

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

@@ -4,8 +4,11 @@ import cron from '../../middlewares/cron';
 const api = {};
 
 /**
- * @api {post} /api/v3/cron Runs cron
+ * @api {post} /api/v3/cron Run cron
  * @apiName Cron
+ * @apiDescription This causes cron to run. It assumes that the user has already been shown
+ * the Record Yesterday's Activity ("Check off any Dailies you did yesterday") screen and
+ * so it will immediately apply damage for incomplete due Dailies.
  * @apiGroup Cron
  *
  * @apiSuccess {Object} data An empty Object

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

@@ -93,7 +93,7 @@ api.getPatrons = {
 };
 
 /**
- * @api {get} /api/v3/hall/heroes Get all Heroes
+ * @api {get} /api/v3/hall/heroes Get all Heroes (contributors)
  * @apiName GetHeroes
  * @apiGroup Hall
  *
@@ -154,7 +154,7 @@ const heroAdminFields = 'contributor balance profile.name purchased items auth f
  * @apiGroup Hall
  * @apiPermission Admin
  *
- * @apiDescription Returns the profile of the given user
+ * @apiDescription Returns the profile of the given user. User does not need to be a contributor.
  *
  * @apiSuccess {Object} data The user object
  *
@@ -208,9 +208,9 @@ const gemsPerTier = {
  * @apiGroup Hall
  * @apiPermission Admin
  *
- * @apiDescription Update user's gem balance, contributions & contribution tier
+ * @apiDescription Update user's gem balance, contributions and contribution tier,
- * and admin status. Grant items, block / unblock user's account
+ * or admin status. Grant items. Block / unblock user's account.
- * and revoke / unrevoke chat privileges.
+ * Revoke / unrevoke chat privileges.
  *
  * @apiExample Example Body:
  * {

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

@@ -658,8 +658,8 @@ api.getObjectionsToInteraction = {
  * @apiName SendPrivateMessage
  * @apiGroup Member
  *
- * @apiParam (Body) {String} message Body parameter - The message
+ * @apiParam (Body) {String} message The message
- * @apiParam (Body) {UUID} toUserId Body parameter - The user to contact
+ * @apiParam (Body) {UUID} toUserId The id of the user to contact
  *
  * @apiSuccess {Object} data.message The message just sent
  *
@@ -698,7 +698,7 @@ api.sendPrivateMessage = {
  * @apiGroup Member
  *
  * @apiParam (Body) {String} message The message to the user
- * @apiParam (Body) {UUID} toUserId The toUser _id
+ * @apiParam (Body) {UUID} toUserId The user to send the gift to
  * @apiParam (Body) {Integer} gemAmount The number of gems to send
  *
  * @apiSuccess {Object} data An empty Object

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

@@ -75,8 +75,10 @@ api.getNews = {
 };
 
 /**
- * @api {post} /api/v3/news/tell-me-later Get latest Bailey announcement in a second moment
+ * @api {post} /api/v3/news/tell-me-later Allow latest Bailey announcement to be read later
  * @apiName TellMeLaterNews
+ * @apiDescription Add a notification to allow viewing of the latest "New Stuff by Bailey" message.
+ * Prevent this specific Bailey message from appearing automatically.
  * @apiGroup News
  *
  *

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

@@ -78,7 +78,7 @@ api.getTags = {
 };
 
 /**
- * @api {get} /api/v3/tags/:tagId Get a tag given its id
+ * @api {get} /api/v3/tags/:tagId Get a tag
  * @apiName GetTag
  * @apiGroup Tag
  *
@@ -199,7 +199,7 @@ api.reorderTags = {
 };
 
 /**
- * @api {delete} /api/v3/tags/:tagId Delete a user tag given its id
+ * @api {delete} /api/v3/tags/:tagId Delete a user tag
  * @apiName DeleteTag
  * @apiGroup Tag
  *

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

@@ -1479,6 +1479,8 @@ api.unlinkOneTask = {
 /**
  * @api {post} /api/v3/tasks/clearCompletedTodos Delete user's completed todos
  * @apiName ClearCompletedTodos
+ * @apiDescription Deletes all of a user's completed To-Dos except
+ * those belonging to active Challenges and Group Plans.
  * @apiGroup Task
  *
  * @apiExample {curl} Example call:
@@ -1523,7 +1525,7 @@ api.clearCompletedTodos = {
 };
 
 /**
- * @api {delete} /api/v3/tasks/:taskId Delete a task given its id
+ * @api {delete} /api/v3/tasks/:taskId Delete a task
  * @apiName DeleteTask
  * @apiGroup Task
  *

website/server/controllers/api-v3/tasks/groups.js

@@ -178,7 +178,7 @@ api.groupMoveTask = {
  * @apiParam (Path) {UUID} taskId The id of the task that will be assigned
  * @apiParam (Path) {UUID} assignedUserId The id of the user that will be assigned to the task
  *
- * @apiSuccess data An object if a single task was created, otherwise an array of tasks
+ * @apiSuccess data The assigned task
  */
 api.assignTask = {
   method: 'POST',
@@ -246,14 +246,14 @@ api.assignTask = {
 
 /**
  * @api {post} /api/v3/tasks/:taskId/unassign/:assignedUserId Unassign a user from a task
- * @apiDescription Unassigns a user to from a group task
+ * @apiDescription Unassigns a user from a group task
  * @apiName UnassignTask
  * @apiGroup Task
  *
- * @apiParam (Path) {UUID} taskId The id of the task that will be assigned
+ * @apiParam (Path) {UUID} taskId The id of the task that is the original group task
  * @apiParam (Path) {UUID} assignedUserId The id of the user that will be unassigned from the task
  *
- * @apiSuccess data An object if a single task was created, otherwise an array of tasks
+ * @apiSuccess data The unassigned task
  */
 api.unassignTask = {
   method: 'POST',
@@ -398,8 +398,8 @@ api.approveTask = {
 };
 
 /**
- * @api {post} /api/v3/tasks/:taskId/needs-work/:userId Group task needs more work
+ * @api {post} /api/v3/tasks/:taskId/needs-work/:userId Require more work for a group task
- * @apiDescription Mark an assigned group task as needeing more work before it can be approved
+ * @apiDescription Mark an assigned group task as needing more work before it can be approved
  * @apiVersion 3.0.0
  * @apiName TaskNeedsWork
  * @apiGroup Task

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

@@ -41,28 +41,28 @@ const api = {};
  * @apiGroup User
  *
  * @apiDescription The user profile contains data related to the authenticated
- * user including (but not limited to);
+ * user including (but not limited to):
- * Achievements
+ * Achievements;
- * Authentications (including types and timestamps)
+ * Authentications (including types and timestamps);
- * Challenges
+ * Challenges memberships (Challenge IDs);
- * Flags (including armoire, tutorial, tour etc...)
+ * Flags (including armoire, tutorial, tour etc...);
- * Guilds
+ * Guilds memberships (Guild IDs);
- * History (including timestamps and values)
+ * History (including timestamps and values, only for Experience and summed To-Do values);
- * Inbox
+ * Inbox;
- * Invitations (to parties/guilds)
+ * Invitations (to parties/guilds);
- * Items (character's full inventory)
+ * Items (character's full inventory);
- * New Messages (flags for groups/guilds that have new messages)
+ * New Messages (flags for party/guilds that have new messages; also reported in Notifications);
- * Notifications
+ * Notifications;
- * Party (includes current quest information)
+ * Party (includes current quest information);
- * Preferences (user selected prefs)
+ * Preferences (user selected prefs);
- * Profile (name, photo url, blurb)
+ * Profile (name, photo url, blurb);
- * Purchased (includes purchase history, gem purchased items, plans)
+ * Purchased (includes subscription data and some gem-purchased items);
- * PushDevices (identifiers for mobile devices authorized)
+ * PushDevices (identifiers for mobile devices authorized);
- * Stats (standard RPG stats, class, buffs, xp, etc..)
+ * Stats (standard RPG stats, class, buffs, xp, etc..);
- * Tags
+ * Tags;
- * TasksOrder (list of all ids for dailys, habits, rewards and todos)
+ * TasksOrder (list of all IDs for Dailys, Habits, Rewards and To-Dos).
  *
- * @apiParam (Query) {String} [userFields] A list of comma separated user fields to
+ * @apiParam (Query) {String} [userFields] A list of comma-separated user fields to
  *                                         be returned instead of the entire document.
  *                                         Notifications are always returned.
  *
@@ -92,7 +92,7 @@ api.getUser = {
 
 /**
  * @api {get} /api/v3/user/inventory/buy
- * Get the gear items available for purchase for the authenticated user
+ * Get equipment/gear items available for purchase for the authenticated user
  * @apiName UserGetBuyList
  * @apiGroup User
  *
@@ -231,7 +231,8 @@ api.updateUser = {
  * @apiName UserDelete
  * @apiGroup User
  *
- * @apiParam (Body) {String} password The user's password if the account uses local authentication
+ * @apiParam (Body) {String} password The user's password if the account uses local authentication,
+ * otherwise the localized word "DELETE"
  * @apiParam (Body) {String} feedback User's optional feedback explaining reasons for deletion
  *
  * @apiSuccess {Object} data An empty Object
@@ -242,9 +243,14 @@ api.updateUser = {
  *   "data": {}
  * }
  *
- * @apiError {BadRequest} MissingPassword The password was not included in the request
+ * @apiError {BadRequest} MissingPassword Missing password.
- * @apiError {BadRequest} LengthExceeded The feedback provided is longer than 10K
+ * @apiError {BadRequest} NotAuthorized Wrong password.
- * @apiError {BadRequest} NotAuthorized There is no account that uses those credentials.
+ * @apiError {BadRequest} NotAuthorized Please type DELETE in all capital letters to
+ * delete your account.
+ * @apiError {BadRequest} BadRequest Account deletion feedback is limited to 10,000 characters.
+ * For lengthy feedback, email ${TECH_ASSISTANCE_EMAIL}.
+ * @apiError {BadRequest} NotAuthorized You have an active subscription,
+ * cancel your plan before deleting your account.
  *
  * @apiErrorExample {json} Example error:
  *  {
@@ -279,7 +285,7 @@ api.deleteUser = {
     }
 
     const { feedback } = req.body;
-    if (feedback && feedback.length > 10000) throw new BadRequest(`Account deletion feedback is limited to 10,000 characters. For lengthy feedback, email ${TECH_ASSISTANCE_EMAIL}.`);
+    if (feedback && feedback.length > 10000) throw new BadRequest(`Account deletion feedback is limited to 10,000 characters. For lengthy feedback, email ${TECH_ASSISTANCE_EMAIL}.`); // @TODO localize this string
 
     if (plan && plan.customerId && !plan.dateTerminated) {
       throw new NotAuthorized(res.t('cannotDeleteActiveAccount'));
@@ -333,14 +339,14 @@ function _cleanChecklist (task) {
  * @apiGroup User
  *
  * @apiDescription Returns the user's data without:
- * Authentication information
+ * Authentication information,
- * NewMessages/Invitations/Inbox
+ * NewMessages/Invitations/Inbox,
- * Profile
+ * Profile,
- * Purchased information
+ * Purchased information,
- * Contributor information
+ * Contributor information,
- * Special items
+ * Special items,
- * Webhooks
+ * Webhooks,
- * Notifications
+ * Notifications.
  *
  * @apiSuccess {Object} data.user
  * @apiSuccess {Object} data.tasks
@@ -537,7 +543,7 @@ api.buyGear = {
 };
 
 /**
- * @api {post} /api/v3/user/buy-armoire Buy an armoire item
+ * @api {post} /api/v3/user/buy-armoire Buy an Enchanted Armoire item
  * @apiName UserBuyArmoire
  * @apiGroup User
  *
@@ -619,8 +625,9 @@ api.buyHealthPotion = {
 };
 
 /**
- * @api {post} /api/v3/user/buy-mystery-set/:key Buy a mystery set
+ * @api {post} /api/v3/user/buy-mystery-set/:key Buy a Mystery Item set
  * @apiName UserBuyMysterySet
+ * @apiDescription This buys a Mystery Item set using an Hourglass.
  * @apiGroup User
  *
  * @apiParam (Path) {String} key The mystery set to buy
@@ -703,7 +710,7 @@ api.buyQuest = {
 };
 
 /**
- * @api {post} /api/v3/user/buy-special-spell/:key Buy special "spell" item
+ * @api {post} /api/v3/user/buy-special-spell/:key Buy special item (card, avatar transformation)
  * @apiDescription Includes gift cards (e.g., birthday card), and avatar Transformation
  * Items and their antidotes (e.g., Snowball item and Salt reward).
  * @apiName UserBuySpecialSpell
@@ -1003,6 +1010,8 @@ api.purchase = {
 /**
  * @api {post} /api/v3/user/purchase-hourglass/:type/:key Purchase Hourglass-purchasable item
  * @apiName UserPurchaseHourglass
+ * @apiDescription Purchases an Hourglass-purchasable item.
+ * Does not include Mystery Item sets (use /api/v3/user/buy-mystery-set/:key).
  * @apiGroup User
  *
  * @apiParam (Path) {String="pets","mounts"} type The type of item to purchase
@@ -1492,7 +1501,7 @@ api.clearMessages = {
 };
 
 /**
- * @api {post} /api/v3/user/mark-pms-read Marks Private Messages as read
+ * @api {post} /api/v3/user/mark-pms-read Mark Private Messages as read
  * @apiName markPmsRead
  * @apiGroup User
  *
@@ -1517,7 +1526,7 @@ api.markPmsRead = {
 /* NOTE this route has also an API v4 version */
 
 /**
- * @api {post} /api/v3/user/reroll Reroll a user using the Fortify Potion
+ * @api {post} /api/v3/user/reroll Reroll a user (reset tasks) using the Fortify Potion
  * @apiName UserReroll
  * @apiGroup User
  *
@@ -1580,14 +1589,12 @@ api.userReset = {
 };
 
 /**
- * @api {post} /api/v3/user/custom-day-start
+ * @api {post} /api/v3/user/custom-day-start Set Custom Day Start time for user.
- * Set preferences.dayStart (Custom Day Start time) for user
  * @apiName setCustomDayStart
  * @apiGroup User
  *
- *
  * @apiParam (Body) {number} [dayStart=0] The hour number 0-23 for day to begin.
- *                                        If body is not included, will default to 0.
+ *                                        If not supplied, will default to 0.
  *
  * @apiParamExample {json} Request-Example:
  * {"dayStart":2}

website/server/controllers/api-v3/user/spells.js

@@ -30,29 +30,30 @@ const api = {};
  *                  the necessary fields will be populated. The user is always returned.
  *
  * @apiDescription Skill Key to Name Mapping
- * Mage
- * fireball: "Burst of Flames"
- * mpheal: "Ethereal Surge"
- * earth: "Earthquake"
- * frost: "Chilling Frost"
  *
- * Warrior
+ * Mage:
- * smash: "Brutal Smash"
+ * fireball="Burst of Flames",
- * defensiveStance: "Defensive Stance"
+ * mpheal="Ethereal Surge",
- * valorousPresence: "Valorous Presence"
+ * earth="Earthquake",
- * intimidate: "Intimidating Gaze"
+ * frost="Chilling Frost"
  *
- * Rogue
+ * Warrior:
- * pickPocket: "Pickpocket"
+ * smash="Brutal Smash",
- * backStab: "Backstab"
+ * defensiveStance="Defensive Stance",
- * toolsOfTrade: "Tools of the Trade"
+ * valorousPresence="Valorous Presence",
- * stealth: "Stealth"
+ * intimidate="Intimidating Gaze"
  *
- * Healer
+ * Rogue:
- * heal: "Healing Light"
+ * pickPocket="Pickpocket",
- * protectAura: "Protective Aura"
+ * backStab="Backstab",
- * brightness: "Searing Brightness"
+ * toolsOfTrade="Tools of the Trade",
- * healAll: "Blessing"
+ * stealth="Stealth"
+ *
+ * Healer:
+ * heal="Healing Light",
+ * protectAura="Protective Aura",
+ * brightness="Searing Brightness",
+ * healAll="Blessing"
  *
  * @apiError (400) {NotAuthorized} Not enough mana.
  * @apiUse TaskNotFound

website/server/controllers/api-v3/user/stats.js

@@ -9,6 +9,7 @@ const api = {};
  * Allocate a single Stat Point (previously called Attribute Point)
  * @apiName UserAllocate
  * @apiGroup User
+ * @apiDescription Allocates a single Stat Point.
  *
  * @apiParam (Query) {String="str","con","int","per"} stat The Stat to increase. Default is 'str'
  *

website/server/controllers/api-v4/inbox.js

@@ -77,7 +77,9 @@ api.clearMessages = {
  * @api {get} /api/v4/inbox/conversations Get the conversations for a user
  * @apiName conversations
  * @apiGroup Inbox
- * @apiDescription Get the conversations for a user
+ * @apiDescription Get the conversations for a user.
+ * This is for API v4 which must not be used in third-party tools.
+ * For API v3, use "Get inbox messages for a user".
  *
  * @apiSuccess {Array} data An array of inbox conversations
  *

website/server/controllers/api-v4/members.js

@@ -5,8 +5,10 @@ const api = {};
 
 /**
  * @api {post} /api/v4/members/flag-private-message/:messageId Flag a private message
- * @apiDescription An email and slack message are sent
+ * @apiDescription Moderators are notified about every flagged message,
- * to the moderators about every flagged message.
+ * including the sender, recipient, and full content of the message.
+ * This is for API v4 which must not be used in third-party tools as it can change without notice.
+ * There is no equivalent route in API v3.
  * @apiName FlagPrivateMessage
  * @apiGroup Member
  *

website/server/controllers/top-level/dataexport.js

@@ -161,6 +161,7 @@ api.exportUserDataJson = {
 /**
  * @api {get} /export/userdata.xml Export user data in XML format
  * @apiName ExportUserDataXml
+ * @apiDescription This XML export feature is not currently working (https://github.com/HabitRPG/habitica/issues/10100).
  * @apiGroup DataExport
  *
  * @apiSuccess {XML} File An xml file of the user object.
@@ -224,6 +225,7 @@ api.exportUserAvatarHtml = {
 /**
  * @api {get} /export/avatar-:uuid.png Render a user avatar as a PNG file
  * @apiName ExportUserAvatarPng
+ * @apiDescription This PNG export feature is not currently working (https://github.com/HabitRPG/habitica/issues/9489).
  * @apiGroup DataExport
  *
  * @apiParam (Path) {String} uuid The User ID of the user
@@ -293,6 +295,7 @@ api.exportUserAvatarPng = {
 /**
  * @api {get} /export/inbox.html Export user private messages as HTML document
  * @apiName ExportUserPrivateMessages
+ * @apiDescription This HTML export feature is not currently working (https://github.com/HabitRPG/habitica/issues/9489).
  * @apiGroup DataExport
  *
  * @apiSuccess {HTML} File An html page of the user's private messages.

website/server/controllers/top-level/email.js

@@ -8,14 +8,15 @@ import {
 const api = {};
 
 /**
- * @api {get} /email/unsubscribe Unsubscribe an email or user from email notifications
+ * @api {get} /email/unsubscribe Unsubscribe an email address or user from email notifications
- * @apiDescription Does not require authentication
  * @apiName UnsubscribeEmail
  * @apiGroup Unsubscribe
  * @apiDescription This is a GET method included in official emails from Habitica
  * that will unsubscribe the user from emails.
+ * Does not require authentication.
  *
- * @apiParam (Query) {String} code An unsubscription code
+ * @apiParam (Query) {String} code An unsubscription code that contains an encrypted User ID or
+ * email address
  *
  * @apiSuccess {String} Webpage An html success message
  *