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)
+ * @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,9 @@ 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. The 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 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

@@ -53,8 +53,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

@@ -1477,8 +1477,9 @@ api.unlinkOneTask = {
 };
 
 /**
- * @api {post} /api/v3/tasks/clearCompletedTodos Delete user's completed todos
+ * @api {post} /api/v3/tasks/clearCompletedTodos Delete user's completed To-Dos
  * @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 +1524,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

@@ -112,8 +112,7 @@ api.getGroupTasks = {
 };
 
 /**
- * @api {post} /api/v3/group/:groupId/tasks/:taskId/move/to/:position Move a group task to
+ * @api {post} /api/v3/group/:groupId/tasks/:taskId/move/to/:position Move a group task to a specified position
- * a specified position
  * @apiDescription Moves a group task to a specified position
  * @apiVersion 3.0.0
  * @apiName GroupMoveTask
@@ -178,7 +177,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 +245,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 +397,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.
  *
@@ -91,8 +91,7 @@ api.getUser = {
 };
 
 /**
- * @api {get} /api/v3/user/inventory/buy Get the gear items available for purchase
+ * @api {get} /api/v3/user/inventory/buy Get the gear items available for purchase for the authenticated user
- * for the authenticated user
  * @apiName UserGetBuyList
  * @apiGroup User
  *
@@ -231,7 +230,7 @@ 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 +241,11 @@ 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}
  *  {
@@ -279,7 +280,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 +334,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 +538,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 +620,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 +705,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, etc)
  * @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 +1005,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 +1496,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 +1521,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 +1584,12 @@ api.userReset = {
 };
 
 /**
- * @api {post} /api/v3/user/custom-day-start Set preferences.dayStart
+ * @api {post} /api/v3/user/custom-day-start Set Custom Day Start time for user.
- * (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}
@@ -1666,8 +1668,7 @@ api.togglePinnedItem = {
 };
 
 /**
- * @api {post} /api/v3/user/move-pinned-item/:type/:path/move/to/:position Move a pinned
+ * @api {post} /api/v3/user/move-pinned-item/:type/:path/move/to/:position Move a pinned item in the rewards column to a new position after being sorted
- * item in the rewards column to a new position after being sorted
  * @apiName MovePinnedItem
  * @apiGroup User
  *

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

@@ -5,8 +5,7 @@ import { authWithHeaders } from '../../../middlewares/auth';
 const api = {};
 
 /**
- * @api {post} /api/v3/user/allocate Allocate a single Stat Point
+ * @api {post} /api/v3/user/allocate Allocate a single Stat Point (previously called Attribute Point)
- * (previously called Attribute Point)
  * @apiName UserAllocate
  * @apiGroup User
  *

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

@@ -77,7 +77,7 @@ 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. Use "Get inbox messages for a user" instead.
  *
  * @apiSuccess {Array} data An array of inbox conversations
  *

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

@@ -5,8 +5,8 @@ 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, including the sender, recipient, and full content of the message.
- * to the moderators about every flagged message.
+ * This route 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. Refer to https://github.com/HabitRPG/habitica/issues/10100 for details.
  * @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. Refer to https://github.com/HabitRPG/habitica/issues/9489 for details.
  * @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. Refer to https://github.com/HabitRPG/habitica/issues/9489 for details.
  * @apiGroup DataExport
  *
  * @apiSuccess {HTML} File An html page of the user's private messages.

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

@@ -8,14 +8,14 @@ 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
  *