Attempt to fix typos in the API doc

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

@@ -219,7 +219,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

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,

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 {String} data.label The label for that category
- * @apiSuccess {Object} data.*.achievements The achievements in that category
+ * @apiSuccess {Object} data.achievements The achievements in that category
  *
- * @apiSuccess {String} data.*.achievements.title The localized title string
+ * @apiSuccess {String} data.achievements.title The localized title string
- * @apiSuccess {String} data.*.achievements.text The localized description string
+ * @apiSuccess {String} data.achievements.text The localized description string
- * @apiSuccess {Boolean} data.*.achievements.earned Whether the user has earned the achievement
+ * @apiSuccess {Boolean} data.achievements.earned Whether the user has earned the achievement
- * @apiSuccess {Number} data.*.achievements.index The unique index assigned
+ * @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

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

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

@@ -112,8 +112,8 @@ 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
- * a specified position
+ * Move a group task to a specified position
  * @apiDescription Moves a group task to a specified position
  * @apiVersion 3.0.0
  * @apiName GroupMoveTask

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

@@ -91,8 +91,8 @@ api.getUser = {
 };
 
 /**
- * @api {get} /api/v3/user/inventory/buy Get the gear items available for purchase
+ * @api {get} /api/v3/user/inventory/buy
- * for the authenticated user
+ * Get the gear items available for purchase for the authenticated user
  * @apiName UserGetBuyList
  * @apiGroup User
  *
@@ -246,7 +246,7 @@ api.updateUser = {
  * @apiError {BadRequest} LengthExceeded The feedback provided is longer than 10K
  * @apiError {BadRequest} NotAuthorized There is no account that uses those credentials.
  *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
  *  {
  *   "success": false,
  *   "error": "BadRequest",
@@ -586,7 +586,7 @@ api.buyArmoire = {
  * @apiSuccess {Object} data User's current stats
  * @apiSuccess {String} message Success message
  *
- * @apiSuccessExample
+ * @apiSuccessExample Example return:
  *  {
  *   "success": true,
  *   "data": {
@@ -669,7 +669,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": {
@@ -815,7 +815,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---},
@@ -857,12 +857,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.
  *
@@ -913,7 +913,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 = {
@@ -968,7 +968,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."}
  */
@@ -1021,7 +1021,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 = {
@@ -1055,7 +1055,7 @@ api.userPurchaseHourglass = {
  * @apiSuccess {Boolean} data.cardReceived user.flags.cardReceived
  * @apiSuccess {String} message Success message
  *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
  *  {
  *   "success": true,
  *   "data": {
@@ -1104,7 +1104,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",
@@ -1123,7 +1123,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 = {
@@ -1145,7 +1145,7 @@ api.userOpenMysteryItem = {
  * @apiSuccess {Object} data.items `user.items.pets`
  * @apiSuccess {String} message Success message
  *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
  *  {
  *   "success": true,
  *   "data": {
@@ -1153,9 +1153,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 = {
@@ -1180,7 +1180,7 @@ api.userReleasePets = {
  * @apiSuccess {Number} data.balance
  * @apiSuccess {String} message Success message
  *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
  *  {
  *   "success": true,
  *   "data": {
@@ -1201,9 +1201,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"}
 
  */
@@ -1227,7 +1227,7 @@ api.userReleaseBoth = {
  * @apiSuccess {Object} data user.items.mounts
  * @apiSuccess {String} message Success message
  *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
  *  {
  *   "success": true,
  *   "data": {
@@ -1237,9 +1237,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"}
  *
  */
@@ -1262,7 +1262,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
@@ -1272,7 +1272,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"}
  */
@@ -1295,7 +1295,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
  *
@@ -1304,7 +1304,7 @@ api.userSell = {
  * @apiSuccess {Object} data.preferences
  * @apiSuccess {String} message "Items have been unlocked"
  *
- * @apiSuccessExample {json}
+ * @apiSuccessExample {json} Example success:
  * {
  *  "success": true,
  *  "data": {},
@@ -1315,7 +1315,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."}
  */
@@ -1342,7 +1342,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 = {
@@ -1368,7 +1368,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": {
@@ -1382,9 +1382,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 = {
@@ -1405,7 +1405,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.
@@ -1433,7 +1433,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": {
@@ -1475,7 +1475,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 = {
@@ -1498,7 +1498,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":[]}
  *
  */
@@ -1525,7 +1525,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": {
@@ -1533,9 +1533,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 = {
@@ -1558,7 +1558,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--},
@@ -1580,8 +1580,8 @@ api.userReset = {
 };
 
 /**
- * @api {post} /api/v3/user/custom-day-start Set preferences.dayStart
+ * @api {post} /api/v3/user/custom-day-start
- * (Custom Day Start time) for user.
+ * Set preferences.dayStart (Custom Day Start time) for user
  * @apiName setCustomDayStart
  * @apiGroup User
  *
@@ -1595,12 +1595,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}]}
@@ -1666,8 +1666,8 @@ 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
- * item in the rewards column to a new position after being sorted
+ * Move a pinned item in the rewards column to a new position after being sorted
  * @apiName MovePinnedItem
  * @apiGroup User
  *
@@ -1678,7 +1678,7 @@ 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":[]}
  *

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

@@ -5,21 +5,21 @@ import { authWithHeaders } from '../../../middlewares/auth';
 const api = {};
 
 /**
- * @api {post} /api/v3/user/allocate Allocate a single Stat Point
+ * @api {post} /api/v3/user/allocate
- * (previously called Attribute Point)
+ * Allocate a single Stat Point (previously called Attribute Point)
  * @apiName UserAllocate
  * @apiGroup User
  *
  * @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 +59,7 @@ api.allocate = {
  *
  * @apiError {NotAuthorized} NoPoints You don't have enough Stat Points.
  *
- * @apiErrorExample {json}
+ * @apiErrorExample {json} Example error:
  *  {
  *   "success": false,
  *   "error": "NotAuthorized",