Merge remote-tracking branch 'upstream/develop' into apidocs-comment-fixes

2025-12-17 22:57:21 +01:00 · 2020-02-20 09:47:44 +10:00
parent 15976e906a 6a483edfe1
commit 0891908cba
218 changed files with 14756 additions and 11762 deletions
--- a/website/server/controllers/api-v3/auth.js
+++ b/website/server/controllers/api-v3/auth.js
@@ -223,7 +223,7 @@ api.updateUsername = {
 };

 /**
- * @api {put} /api/v3/user/auth/update-password
+ * @api {put} /api/v3/user/auth/update-password Update password
 * @apiDescription Update the password of a local user
 * @apiName UpdatePassword
 * @apiGroup User
--- a/website/server/controllers/api-v3/coupon.js
+++ b/website/server/controllers/api-v3/coupon.js
@@ -25,7 +25,7 @@ const api = {};
 *
 * @apiSuccess {String} Coupons in CSV format
 *
- * @apiSuccessExample {String}
+ * @apiSuccessExample {String} Example success:
 * code,event,date,user
 * GJG4-WEA4-QX3P,wondercon,1476929528704,user-uuid
 * TT32-EYQA-JPBT,wondercon,1476929528705,
--- a/website/server/controllers/api-v3/members.js
+++ b/website/server/controllers/api-v3/members.js
@@ -167,17 +167,17 @@ api.getMemberByUsername = {
 * @apiSuccess {Object} data.seasonal The seasonal achievements object
 * @apiSuccess {Object} data.special The special achievements object
 *
- * @apiSuccess {String} data.*.label The label for that category
- * @apiSuccess {Object} data.*.achievements The achievements in that category
+ * @apiSuccess {String} data.label The label for that category
+ * @apiSuccess {Object} data.achievements The achievements in that category
 *
- * @apiSuccess {String} data.*.achievements.title The localized title string
- * @apiSuccess {String} data.*.achievements.text The localized description string
- * @apiSuccess {Boolean} data.*.achievements.earned Whether the user has earned the achievement
- * @apiSuccess {Number} data.*.achievements.index The unique index assigned
+ * @apiSuccess {String} data.achievements.title The localized title string
+ * @apiSuccess {String} data.achievements.text The localized description string
+ * @apiSuccess {Boolean} data.achievements.earned Whether the user has earned the achievement
+ * @apiSuccess {Number} data.achievements.index The unique index assigned
 *                                                to the achievement (only for sorting purposes).
- * @apiSuccess {Anything} data.*.achievements.value The value related to the achievement
+ * @apiSuccess {Anything} data.achievements.value The value related to the achievement
 *                                                  (if applicable)
- * @apiSuccess {Number} data.*.achievements.optionalCount The count related to the achievement
+ * @apiSuccess {Number} data.achievements.optionalCount The count related to the achievement
 *                                                        (if applicable)
 *
 * @apiSuccessExample {json} Successful Response
--- a/website/server/controllers/api-v3/news.js
+++ b/website/server/controllers/api-v3/news.js
@@ -4,7 +4,7 @@ const api = {};

 // @TODO export this const, cannot export it from here because only routes are exported from
 // controllers
-const LAST_ANNOUNCEMENT_TITLE = 'BLOG POST: PET FOOD PREFERENCES';
+const LAST_ANNOUNCEMENT_TITLE = 'NEW PET COLLECTION BADGES!';
 const worldDmg = { // @TODO
  bailey: false,
 };
@@ -31,21 +31,23 @@ api.getNews = {
          <div class="mr-3 ${baileyClass}"></div>
          <div class="media-body">
            <h1 class="align-self-center">${res.t('newStuff')}</h1>
-            <h2>2/6/2020 - ${LAST_ANNOUNCEMENT_TITLE}</h2>
+            <h2>2/18/2020 - ${LAST_ANNOUNCEMENT_TITLE}</h2>
          </div>
        </div>
        <hr/>
-        <div class="scene_cake center-block"></div>
+        <div class="promo_achievement_CottonCandyPink center-block"></div>
        <p>
-          This month's <a href='https://habitica.wordpress.com/2020/02/05/food-preferences/'
-          target='_blank'>featured Wiki article</a> is about Pet Food Preferences! We hope that it
-          will help you as you hatch and raise your own Habitican menagerie. Be sure to check it
-          out, and let us know what you think by reaching out on <a
-          href='https://twitter.com/habitica' target='_blank'>Twitter</a>, <a
-          href='http://blog.habitrpg.com' target='_blank'>Tumblr</a>, and <a
-          href='https://facebook.com/habitica' target='_blank'>Facebook</a>.
+          We're releasing a new achievement so you can celebrate your successes in the world of
+          Habitican pet collecting! Earn the Tickled Pink and Rosy Outlook achievements by
+          collecting Cotton Candy Pink pets and mounts and you'll earn a nifty badge for your
+          profile.
        </p>
-        <div class="small mb-3">by shanaqui and the Wiki Wizards</div>
+        <p>
+          If you already have all the Cotton Candy Pink pets and/or mounts in your stable, you'll
+          receive the badge automatically! Check your profile and celebrate your new achievement
+          with pride in your pink prowess.
+        </p>
+        <div class="small mb-3">by Piyowo and SabreCat</div>
      </div>
      `,
    });
--- a/website/server/controllers/api-v3/quests.js
+++ b/website/server/controllers/api-v3/quests.js
@@ -190,7 +190,7 @@ api.acceptQuest = {
    if (!group) throw new NotFound(res.t('groupNotFound'));
    if (group.type !== 'party') throw new NotAuthorized(res.t('guildQuestsNotSupported'));
    if (!group.quest.key) throw new NotFound(res.t('questInviteNotFound'));
-    if (group.quest.active) throw new NotAuthorized(res.t('questAlreadyUnderway'));
+    if (group.quest.active) throw new NotAuthorized(res.t('questAlreadyStartedFriendly'));
    if (group.quest.members[user._id]) throw new BadRequest(res.t('questAlreadyAccepted'));

    user.party.quest.RSVPNeeded = false;
@@ -248,7 +248,7 @@ api.rejectQuest = {
    if (!group) throw new NotFound(res.t('groupNotFound'));
    if (group.type !== 'party') throw new NotAuthorized(res.t('guildQuestsNotSupported'));
    if (!group.quest.key) throw new NotFound(res.t('questInvitationDoesNotExist'));
-    if (group.quest.active) throw new NotAuthorized(res.t('questAlreadyUnderway'));
+    if (group.quest.active) throw new NotAuthorized(res.t('questAlreadyStartedFriendly'));
    if (group.quest.members[user._id]) throw new BadRequest(res.t('questAlreadyAccepted'));
    if (group.quest.members[user._id] === false) throw new BadRequest(res.t('questAlreadyRejected'));

@@ -312,7 +312,7 @@ api.forceStart = {
    if (!group) throw new NotFound(res.t('groupNotFound'));
    if (group.type !== 'party') throw new NotAuthorized(res.t('guildQuestsNotSupported'));
    if (!group.quest.key) throw new NotFound(res.t('questNotPending'));
-    if (group.quest.active) throw new NotAuthorized(res.t('questAlreadyUnderway'));
+    if (group.quest.active) throw new NotAuthorized(res.t('questAlreadyStarted'));
    if (!(user._id === group.quest.leader || user._id === group.leader)) {
      throw new NotAuthorized(res.t('questOrGroupLeaderOnlyStartQuest'));
    }
--- a/website/server/controllers/api-v3/tasks.js
+++ b/website/server/controllers/api-v3/tasks.js
@@ -45,7 +45,7 @@ function canNotEditTasks (group, user, assignedUserId) {

 /**
 * @apiDefine NotAuthorized
- * @apiError (401) {NotAuthorized} There is no account that uses those credentials.
+ * @apiError (401) {NotAuthorized} NoAccount There is no account that uses those credentials.
 */

 const api = {};
@@ -174,7 +174,7 @@ const requiredGroupFields = '_id leader tasksOrder name';
 *                                                     underscores and dashes.
 * @apiError (400) {BadRequest} Value-ValidationFailed `x` is not a valid enum value
 *                                                     for path `(body param)`.
- * @apiError (401) {NotAuthorized} There is no account that uses those credentials.
+ * @apiError (401) {NotAuthorized} NoAccount There is no account that uses those credentials.
 *
 * @apiErrorExample {json} Error-Response:
 *     {
@@ -301,7 +301,7 @@ api.createUserTasks = {
 *                                                     and dashes.
 * @apiError (400) {BadRequest} Value-ValidationFailed `x` is not a valid enum value
 *                                                     for path `(body param)`.
- * @apiError (401) {NotAuthorized} There is no account that uses those credentials.
+ * @apiError (401) {NotAuthorized} NoAccount There is no account that uses those credentials.
 */
 api.createChallengeTasks = {
  method: 'POST',
@@ -359,7 +359,7 @@ api.createChallengeTasks = {
 *
 * @apiSuccess {Array} data An array of tasks
 *
- * @apiSuccessExample
+ * @apiSuccessExample {json} Example return:
 * {"success":true,"data":[{"_id":"8a9d461b-f5eb-4a16-97d3-c03380c422a3",
 * "userId":"b0413351-405f-416f-8787-947ec1c85199","text":"15 minute break",
 * "type":"reward","notes":"","tags":[],"value":10,"priority":1,"attribute":"str",
@@ -379,7 +379,7 @@ api.createChallengeTasks = {
 *
 * @apiError (BadRequest) Invalid_request_parameters Error returned if the
 *                                                   type URL param was not correct.
- * @apiError (401) {NotAuthorized} There is no account that uses those credentials.
+ * @apiError (401) {NotAuthorized} NoAccount There is no account that uses those credentials.
 */
 api.getUserTasks = {
  method: 'GET',
@@ -418,7 +418,7 @@ api.getUserTasks = {
 *
 * @apiSuccess {Array} data An array of tasks
 *
- * @apiSuccessExample
+ * @apiSuccessExample {json} Example return:
 * {"success":true,"data":[{"_id":"5f12bfba-da30-4733-ad01-9c42f9817975",
 * "text":"API Trial","type":"habit","notes":"","tags":[],"value":27.70767809690112,
 * "priority":1.5,"attribute":"str","challenge":{"id":"f23c12f2-5830-4f15-9c36-e17fd729a812"},
@@ -484,7 +484,7 @@ api.getChallengeTasks = {
 *
 * @apiSuccess {Object} data The task object
 *
- * @apiSuccessExample {json} Example returned object
+ * @apiSuccessExample {json} Example returned object:
 * {"success":true,"data":{"_id":"2b774d70-ec8b-41c1-8967-eb6b13d962ba",
 * "userId":"b0413351-405f-416f-8787-947ec1c85199","text":"API Trial",
 * "alias":"apiTrial","type":"habit","notes":"","tags":[],"value":11.996661122825959,
@@ -911,7 +911,7 @@ api.scoreTask = {
 *
 * @apiSuccess {Array} data The new tasks order for the specific type that the taskID belongs to.
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example return:
 * {"success":true,"data":["8d7e237a-b259-46ee-b431-33621256bb0b",
 * "2b774d70-ec8b-41c1-8967-eb6b13d962ba","f03d4a2b-9c36-4f33-9b5f-bae0aed23a49"],
 * "notifications":[]}
@@ -1362,7 +1362,7 @@ api.removeTagFromTask = {
 *                                                         should be kept(keep-all) or
 *                                                         removed(remove-all) after the unlink.
 *
- * @apiExample {curl}
+ * @apiExample {curl} Example call:
 * curl -X "POST" https://habitica.com/api/v3/tasks/unlink-all/f23c12f2-5830-4f15-9c36-e17fd729a812?keep=remove-all
 *
 * @apiSuccess {Object} data An empty object
--- a/website/server/controllers/api-v3/tasks/groups.js
+++ b/website/server/controllers/api-v3/tasks/groups.js
@@ -111,9 +111,9 @@ api.getGroupTasks = {
  },
 };

-/* eslint-disable max-len */
 /**
- * @api {post} /api/v3/group/:groupId/tasks/:taskId/move/to/:position Move group task to new position
+ * @api {post} /api/v3/group/:groupId/tasks/:taskId/move/to/:position
+ * Move a group task to a specified position
 * @apiDescription Moves a group task to a specified position
 * @apiVersion 3.0.0
 * @apiName GroupMoveTask
@@ -125,7 +125,6 @@ api.getGroupTasks = {
 *
 * @apiSuccess {Array} data The new tasks order (group.tasksOrder.{task.type}s)
 */
-/* eslint-enable max-len */
 api.groupMoveTask = {
  method: 'POST',
  url: '/group-tasks/:taskId/move/to/:position',
--- a/website/server/controllers/api-v3/user.js
+++ b/website/server/controllers/api-v3/user.js
@@ -91,7 +91,8 @@ api.getUser = {
 };

 /**
- * @api {get} /api/v3/user/inventory/buy Get equipment/gear items available for user to purchase
+ * @api {get} /api/v3/user/inventory/buy
+ * Get equipment/gear items available for purchase for the authenticated user
 * @apiName UserGetBuyList
 * @apiGroup User
 *
@@ -251,7 +252,7 @@ api.updateUser = {
 * @apiError {BadRequest} NotAuthorized You have an active subscription,
 * cancel your plan before deleting your account.
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 *  {
 *   "success": false,
 *   "error": "BadRequest",
@@ -591,7 +592,7 @@ api.buyArmoire = {
 * @apiSuccess {Object} data User's current stats
 * @apiSuccess {String} message Success message
 *
- * @apiSuccessExample
+ * @apiSuccessExample Example return:
 *  {
 *   "success": true,
 *   "data": {
@@ -675,7 +676,7 @@ api.buyMysterySet = {
 * @apiSuccess {Object} data.quests User's quest list
 * @apiSuccess {String} message Success message
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Success response:
 * {
 *   "success": true,
 *   "data": {
@@ -821,7 +822,7 @@ api.hatch = {
 * @apiSuccess {Object} data user.items
 * @apiSuccess {String} message Optional success message for unequipping an items
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example return:
 *  {
 *   "success": true,
 *   "data": {---DATA TRUNCATED---},
@@ -863,12 +864,12 @@ api.equip = {
 * @apiSuccess {Number} data The pet value
 * @apiSuccess {String} message Success message
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
 * {"success":true,"data":10,"message":"Shade Armadillo
 * really likes the Chocolate!","notifications":[]}
 *
 * @apiError {NotFound} PetNotOwned :pet not found in user.items.pets
- * @apiError {BedRequest} InvalidPet Invalid pet name supplied.
+ * @apiError {BadRequest} InvalidPet Invalid pet name supplied.
 * @apiError {NotFound} FoodNotOwned :food not found in user.items.food
 *                                   Note: also sent if food name is invalid.
 *
@@ -919,7 +920,7 @@ api.feed = {
 *                           selected and gems needed to be paid.
 * @apiError {NotAuthorized} Level To change class you must be at least level 10.
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 * {"success":false,"error":"NotAuthorized","message":"Not enough Gems"}
 */
 api.changeClass = {
@@ -961,7 +962,7 @@ api.disableClasses = {
 * @apiGroup User
 *
 * @apiParam (Path) {String="gems","eggs","hatchingPotions","premiumHatchingPotions"
-                    ,food","quests","gear"} type Type of item to purchase.
+                    ,"food","quests","gear"} type Type of item to purchase.
 * @apiParam (Path) {String} key Item's key (use "gem" for purchasing gems)
 *
 * @apiSuccess {Object} data.items user.items
@@ -974,7 +975,7 @@ api.disableClasses = {
 * @apiError {NotFound} Key Key not found for Content type.
 * @apiError {NotFound} Type Type invalid.
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 * {"success":false,"error":"NotAuthorized","message":
 * "This item is not currently available for purchase."}
 */
@@ -1029,7 +1030,7 @@ api.purchase = {
 * @apiError {BadRequest} Quantity Quantity to purchase must be a number.
 * @apiError {NotFound} Type Type invalid.
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 * {"success":false,"error":"NotAuthorized","message":"You don't have enough Mystic Hourglasses."}
 */
 api.userPurchaseHourglass = {
@@ -1063,7 +1064,7 @@ api.userPurchaseHourglass = {
 * @apiSuccess {Boolean} data.cardReceived user.flags.cardReceived
 * @apiSuccess {String} message Success message
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
 *  {
 *   "success": true,
 *   "data": {
@@ -1112,7 +1113,7 @@ api.readCard = {
 * @apiSuccess {Object} data The item obtained
 * @apiSuccess {String} message Success message
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
 * { "success": true,
 *   "data": {
 *     "mystery": "201612",
@@ -1131,7 +1132,7 @@ api.readCard = {
 *
 * @apiError {BadRequest} Empty No mystery items to open.
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 * {"success":false,"error":"BadRequest","message":"Mystery items are empty"}
 */
 api.userOpenMysteryItem = {
@@ -1153,7 +1154,7 @@ api.userOpenMysteryItem = {
 * @apiSuccess {Object} data.items `user.items.pets`
 * @apiSuccess {String} message Success message
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
 *  {
 *   "success": true,
 *   "data": {
@@ -1161,9 +1162,9 @@ api.userOpenMysteryItem = {
 *   "message": "Pets released"
 * }
 *
- * @apiError {NotAuthorized} Not enough gems
+ * @apiError {NotAuthorized} Gems Not enough gems
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 * {"success":false,"error":"NotAuthorized","message":"Not enough Gems"}
 */
 api.userReleasePets = {
@@ -1188,7 +1189,7 @@ api.userReleasePets = {
 * @apiSuccess {Number} data.balance
 * @apiSuccess {String} message Success message
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
 *  {
 *   "success": true,
 *   "data": {
@@ -1209,9 +1210,9 @@ api.userReleasePets = {
 *   "message": "Mounts and pets released"
 * }
 *
- * @apiError {NotAuthorized} Not enough gems
+ * @apiError {NotAuthorized} Gems Not enough gems
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 * {"success":false,"error":"NotAuthorized","message":"Not enough Gems"}

 */
@@ -1235,7 +1236,7 @@ api.userReleaseBoth = {
 * @apiSuccess {Object} data user.items.mounts
 * @apiSuccess {String} message Success message
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
 *  {
 *   "success": true,
 *   "data": {
@@ -1245,9 +1246,9 @@ api.userReleaseBoth = {
 *   "message": "Mounts released"
 * }
 *
- * @apiError {NotAuthorized} Not enough gems
+ * @apiError {NotAuthorized} Gems Not enough gems
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 * {"success":false,"error":"NotAuthorized","message":"Not enough Gems"}
 *
 */
@@ -1270,7 +1271,7 @@ api.userReleaseMounts = {
 *
 * @apiParam (Path) {String="eggs","hatchingPotions","food"} type The type of item to sell.
 * @apiParam (Path) {String} key The key of the item
- * @apiParam (Query) {Number} (optional) amount The amount to sell
+ * @apiParam (Query) {Number} [amount] The amount to sell
 *
 * @apiSuccess {Object} data.stats
 * @apiSuccess {Object} data.items
@@ -1280,7 +1281,7 @@ api.userReleaseMounts = {
 *                                 user has none in inventory).
 * @apiError {NotAuthorized} InvalidType Type is not a valid type.
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 * {"success":false,"error":"NotAuthorized","message":"Type is not sellable.
 * Must be one of the following eggs, hatchingPotions, food"}
 */
@@ -1303,7 +1304,7 @@ api.userSell = {
 *
 * @apiParam (Query) {String} path Full path to unlock. See "content" API call for list of items.
 *
- * @apiParamExample {curl}
+ * @apiParamExample {curl} Example call:
 * curl -X POST http://habitica.com/api/v3/user/unlock?path=background.midnight_clouds
 * curl -X POST http://habitica.com/api/v3/user/unlock?path=hair.color.midnight
 *
@@ -1312,7 +1313,7 @@ api.userSell = {
 * @apiSuccess {Object} data.preferences
 * @apiSuccess {String} message "Items have been unlocked"
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
 * {
 *  "success": true,
 *  "data": {},
@@ -1323,7 +1324,7 @@ api.userSell = {
 * @apiError {NotAuthorized} Gems Not enough gems available.
 * @apiError {NotAuthorized} Unlocked Full set already unlocked.
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 * {"success":false,"error":"BadRequest","message":"Path string is required"}
 * {"success":false,"error":"NotAuthorized","message":"Full set already unlocked."}
 */
@@ -1350,7 +1351,7 @@ api.userUnlock = {
 *
 * @apiError {NotAuthorized} NotDead Cannot revive player if player is not dead yet
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 * {"success":false,"error":"NotAuthorized","message":"Cannot revive if not dead"}
 */
 api.userRevive = {
@@ -1376,7 +1377,7 @@ api.userRevive = {
 * @apiSuccess {Array} data.tasks User's modified tasks (no rewards)
 * @apiSuccess {String} message Success message
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
 *  {
 *   "success": true,
 *   "data": {
@@ -1390,9 +1391,9 @@ api.userRevive = {
 *   ]
 * }
 *
- * @apiError {NotAuthorized} Not enough gems
+ * @apiError {NotAuthorized} Gems Not enough gems
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 * {"success":false,"error":"NotAuthorized","message":"Not enough Gems"}
 */
 api.userRebirth = {
@@ -1413,7 +1414,7 @@ api.userRebirth = {
 *
 * @apiSuccess {Array} data user.inbox.blocks
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example return:
 * {"success":true,"data":["e4842579-g987-d2d2-8660-2f79e725fb79"],"notifications":[]}
 *
 * @apiError {BadRequest} InvalidUUID UUID is incorrect.
@@ -1441,7 +1442,7 @@ api.blockUser = {
 * @apiParam (Path) {UUID} id The id of the message to delete
 *
 * @apiSuccess {Object} data user.inbox.messages
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example return:
 * {
 *   "success": true,
 *   "data": {
@@ -1483,7 +1484,7 @@ api.deleteMessage = {
 *
 * @apiSuccess {Object} data user.inbox.messages which should be empty
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example return:
 * {"success":true,"data":{},"notifications":[]}
 */
 api.clearMessages = {
@@ -1506,7 +1507,7 @@ api.clearMessages = {
 *
 * @apiSuccess {Object} data user.inbox.newMessages
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example return:
 * {"success":true,"data":[0,"Your private messages have been marked as read"],"notifications":[]}
 *
 */
@@ -1533,7 +1534,7 @@ api.markPmsRead = {
 * @apiSuccess {Object} data.tasks User's modified tasks (no rewards)
 * @apiSuccess {Object} message Success message
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
 *  {
 *   "success": true,
 *   "data": {
@@ -1541,9 +1542,9 @@ api.markPmsRead = {
 *   "message": "Fortify complete!"
 * }
 *
- * @apiError {NotAuthorized} Not enough gems
+ * @apiError {NotAuthorized} Gems Not enough gems
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 * {"success":false,"error":"NotAuthorized","message":"Not enough Gems"}
 */
 api.userReroll = {
@@ -1566,7 +1567,7 @@ api.userReroll = {
 * @apiSuccess {Array} data.tasksToRemove IDs of removed tasks
 * @apiSuccess {String} message Success message
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
 *  {
 *   "success": true,
 *   "data": {--TRUNCATED--},
@@ -1601,12 +1602,12 @@ api.userReset = {
 * @apiSuccess {Object} data An empty Object
 * @apiSuccess {String} message Success message
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Success-Example:
 * {"success":true,"data":{"message":"Your custom day start has changed."},"notifications":[]}
 *
 * @apiError {BadRequest} Validation Value provided is not a number, or is outside the range of 0-23
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Error-Example:
 * {"success":false,"error":"BadRequest","message":"User validation failed",
 * "errors":[{"message":"Path `preferences.dayStart` (25) is more than maximum allowed value (23)."
 * ,"path":"preferences.dayStart","value":25}]}
@@ -1671,9 +1672,9 @@ api.togglePinnedItem = {
  },
 };

-/* eslint-disable max-len */
 /**
- * @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
+ * @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
 * @apiName MovePinnedItem
 * @apiGroup User
 *
@@ -1684,13 +1685,12 @@ api.togglePinnedItem = {
 *
 * @apiSuccess {Array} data The new pinned items order.
 *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
 * {"success":true,"data":{"path":"quests.mayhemMistiflying3","type":"quests",
 * "_id": "5a32d357232feb3bc94c2bdf"},"notifications":[]}
 *
 * @apiUse TaskNotFound
 */
-/* eslint-enable max-len */
 api.movePinnedItem = {
  method: 'POST',
  url: '/user/move-pinned-item/:path/move/to/:position',
--- a/website/server/controllers/api-v3/user/stats.js
+++ b/website/server/controllers/api-v3/user/stats.js
@@ -5,21 +5,22 @@ 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)
 * @apiName UserAllocate
 * @apiGroup User
- * @apiDescription Allocates a single Stat Point (previously called Attribute Point).
+ * @apiDescription Allocates a single Stat Point.
 *
 * @apiParam (Query) {String="str","con","int","per"} stat The Stat to increase. Default is 'str'
 *
- * @apiParamExample {curl}
+ * @apiParamExample {curl} Example call:
 * curl -X POST -d "" https://habitica.com/api/v3/user/allocate?stat=int
 *
 * @apiSuccess {Object} data Returns stats and notifications from the user profile
 *
 * @apiError {NotAuthorized} NoPoints You don't have enough Stat Points.
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 *  {
 *   "success": false,
 *   "error": "NotAuthorized",
@@ -59,7 +60,7 @@ api.allocate = {
 *
 * @apiError {NotAuthorized} NoPoints You don't have enough Stat Points.
 *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
 *  {
 *   "success": false,
 *   "error": "NotAuthorized",