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.
2025-12-18 07:07:35 +01:00 · 2020-02-24 21:22:29 +01:00
parent e502588abc 0891908cba
commit 0280513a00
16 changed files with 125 additions and 97 deletions
--- a/website/server/controllers/api-v3/auth.js
+++ b/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
 *
--- a/website/server/controllers/api-v3/challenges.js
+++ b/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
 *
--- a/website/server/controllers/api-v3/cron.js
+++ b/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
--- a/website/server/controllers/api-v3/hall.js
+++ b/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
- * and admin status. Grant items, block / unblock user's account
- * and revoke / unrevoke chat privileges.
+ * @apiDescription Update user's gem balance, contributions and contribution tier,
+ * or admin status. Grant items. Block / unblock user's account.
+ * Revoke / unrevoke chat privileges.
 *
 * @apiExample Example Body:
 * {
--- a/website/server/controllers/api-v3/members.js
+++ b/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) {UUID} toUserId Body parameter - The user to contact
+ * @apiParam (Body) {String} message The message
+ * @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
--- a/website/server/controllers/api-v3/news.js
+++ b/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
 *
 *
--- a/website/server/controllers/api-v3/tags.js
+++ b/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
 *
--- a/website/server/controllers/api-v3/tasks.js
+++ b/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
 *
--- a/website/server/controllers/api-v3/tasks/groups.js
+++ b/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
- * @apiDescription Mark an assigned group task as needeing more work before it can be approved
+ * @api {post} /api/v3/tasks/:taskId/needs-work/:userId Require more work for a group task
+ * @apiDescription Mark an assigned group task as needing more work before it can be approved
 * @apiVersion 3.0.0
 * @apiName TaskNeedsWork
 * @apiGroup Task
--- a/website/server/controllers/api-v3/user.js
+++ b/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);
- * Achievements
- * Authentications (including types and timestamps)
- * Challenges
- * Flags (including armoire, tutorial, tour etc...)
- * Guilds
- * History (including timestamps and values)
- * Inbox
- * Invitations (to parties/guilds)
- * Items (character's full inventory)
- * New Messages (flags for groups/guilds that have new messages)
- * Notifications
- * Party (includes current quest information)
- * Preferences (user selected prefs)
- * Profile (name, photo url, blurb)
- * Purchased (includes purchase history, gem purchased items, plans)
- * PushDevices (identifiers for mobile devices authorized)
- * Stats (standard RPG stats, class, buffs, xp, etc..)
- * Tags
- * TasksOrder (list of all ids for dailys, habits, rewards and todos)
+ * user including (but not limited to):
+ * Achievements;
+ * Authentications (including types and timestamps);
+ * Challenges memberships (Challenge IDs);
+ * Flags (including armoire, tutorial, tour etc...);
+ * Guilds memberships (Guild IDs);
+ * History (including timestamps and values, only for Experience and summed To-Do values);
+ * Inbox;
+ * Invitations (to parties/guilds);
+ * Items (character's full inventory);
+ * New Messages (flags for party/guilds that have new messages; also reported in Notifications);
+ * Notifications;
+ * Party (includes current quest information);
+ * Preferences (user selected prefs);
+ * Profile (name, photo url, blurb);
+ * Purchased (includes subscription data and some gem-purchased items);
+ * PushDevices (identifiers for mobile devices authorized);
+ * Stats (standard RPG stats, class, buffs, xp, etc..);
+ * Tags;
+ * 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} LengthExceeded The feedback provided is longer than 10K
- * @apiError {BadRequest} NotAuthorized There is no account that uses those credentials.
+ * @apiError {BadRequest} MissingPassword Missing password.
+ * @apiError {BadRequest} NotAuthorized Wrong password.
+ * @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
- * NewMessages/Invitations/Inbox
- * Profile
- * Purchased information
- * Contributor information
- * Special items
- * Webhooks
- * Notifications
+ * Authentication information,
+ * NewMessages/Invitations/Inbox,
+ * Profile,
+ * Purchased information,
+ * Contributor information,
+ * Special items,
+ * Webhooks,
+ * 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
- * Set preferences.dayStart (Custom Day Start time) for user
+ * @api {post} /api/v3/user/custom-day-start Set 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}
--- a/website/server/controllers/api-v3/user/spells.js
+++ b/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
- * smash: "Brutal Smash"
- * defensiveStance: "Defensive Stance"
- * valorousPresence: "Valorous Presence"
- * intimidate: "Intimidating Gaze"
+ * Mage:
+ * fireball="Burst of Flames",
+ * mpheal="Ethereal Surge",
+ * earth="Earthquake",
+ * frost="Chilling Frost"
 *
- * Rogue
- * pickPocket: "Pickpocket"
- * backStab: "Backstab"
- * toolsOfTrade: "Tools of the Trade"
- * stealth: "Stealth"
+ * Warrior:
+ * smash="Brutal Smash",
+ * defensiveStance="Defensive Stance",
+ * valorousPresence="Valorous Presence",
+ * intimidate="Intimidating Gaze"
 *
- * Healer
- * heal: "Healing Light"
- * protectAura: "Protective Aura"
- * brightness: "Searing Brightness"
- * healAll: "Blessing"
+ * Rogue:
+ * pickPocket="Pickpocket",
+ * backStab="Backstab",
+ * toolsOfTrade="Tools of the Trade",
+ * stealth="Stealth"
+ *
+ * Healer:
+ * heal="Healing Light",
+ * protectAura="Protective Aura",
+ * brightness="Searing Brightness",
+ * healAll="Blessing"
 *
 * @apiError (400) {NotAuthorized} Not enough mana.
 * @apiUse TaskNotFound
--- a/website/server/controllers/api-v3/user/stats.js
+++ b/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'
 *
--- a/website/server/controllers/api-v4/inbox.js
+++ b/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
 *
--- a/website/server/controllers/api-v4/members.js
+++ b/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
- * to the moderators about every flagged message.
+ * @apiDescription Moderators are notified 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
 *
--- a/website/server/controllers/top-level/dataexport.js
+++ b/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.
--- a/website/server/controllers/top-level/email.js
+++ b/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
- * @apiDescription Does not require authentication
+ * @api {get} /email/unsubscribe Unsubscribe an email address or user from email notifications
 * @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
 *