adjust text in apidocs for errors / clarity / consistency / standard terminology (no code changes) (#7298)

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

@@ -61,7 +61,7 @@ async function saveContentToDisk (language, content) {
 }
 
 /**
- * @api {get} /api/v3/content Get all available content objects.
+ * @api {get} /api/v3/content Get all available content objects
  * @apiDescription Does not require authentication.
  * @apiVersion 3.0.0
  * @apiName ContentGet

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

@@ -7,7 +7,7 @@ import _ from 'lodash';
 let api = {};
 
 /**
- * @api {post} /api/v3/debug/add-ten-gems Add ten gems to the current user.
+ * @api {post} /api/v3/debug/add-ten-gems Add ten gems to the current user
  * @apiDescription Only available in development mode.
  * @apiVersion 3.0.0
  * @apiName AddTenGems
@@ -31,7 +31,7 @@ api.addTenGems = {
 };
 
 /**
- * @api {post} /api/v3/debug/add-hourglass Add Hourglass to the current user.
+ * @api {post} /api/v3/debug/add-hourglass Add Hourglass to the current user
  * @apiDescription Only available in development mode.
  * @apiVersion 3.0.0
  * @apiName AddHourglass

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

@@ -9,8 +9,8 @@ import _ from 'lodash';
 let api = {};
 
 /**
- * @api {get} /api/v3/hall/patrons Get all Patrons.
+ * @api {get} /api/v3/hall/patrons Get all patrons
- * @apiDescription Only the first 50 patrons are returned. More can be accessed passing ?page=n.
+ * @apiDescription Only the first 50 patrons are returned. More can be accessed passing ?page=n
  * @apiVersion 3.0.0
  * @apiName GetPatrons
  * @apiGroup Hall
@@ -79,13 +79,13 @@ api.getHeroes = {
 const heroAdminFields = 'contributor balance profile.name purchased items auth';
 
 /**
- * @api {get} /api/v3/hall/heroes/:heroId Get an hero given his _id.
+ * @api {get} /api/v3/hall/heroes/:heroId Get any user ("hero") given the UUID
- * @apiDescription Must be an admin to make this request
+ * @apiDescription Must be an admin to make this request.
  * @apiVersion 3.0.0
  * @apiName GetHero
  * @apiGroup Hall
  *
- * @apiSuccess {Object} data The hero object
+ * @apiSuccess {Object} data The user object
  */
 api.getHero = {
   method: 'GET',
@@ -117,13 +117,13 @@ api.getHero = {
 const gemsPerTier = {1: 3, 2: 3, 3: 3, 4: 4, 5: 4, 6: 4, 7: 4, 8: 0, 9: 0};
 
 /**
- * @api {put} /api/v3/hall/heroes/:heroId Update an hero.
+ * @api {put} /api/v3/hall/heroes/:heroId Update any user ("hero")
- * @apiDescription Must be an admin to make this request
+ * @apiDescription Must be an admin to make this request.
  * @apiVersion 3.0.0
  * @apiName UpdateHero
  * @apiGroup Hall
  *
- * @apiSuccess {Object} data The updated hero object
+ * @apiSuccess {Object} data The updated user object
  */
 api.updateHero = {
   method: 'PUT',

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

@@ -6,7 +6,7 @@ let tasksModels = ['habit', 'daily', 'todo', 'reward'];
 let allModels = ['user', 'tag', 'challenge', 'group'].concat(tasksModels);
 
 /**
- * @api {get} /api/v3/models/:model/paths Get all paths for the specified model.
+ * @api {get} /api/v3/models/:model/paths Get all paths for the specified model
  * @apiDescription Doesn't require authentication
  * @apiVersion 3.0.0
  * @apiName GetUserModelPaths

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

@@ -54,7 +54,7 @@ async function _createTasks (req, res, user, challenge) {
 }
 
 /**
- * @api {post} /api/v3/tasks/user Create a new task belonging to the user.
+ * @api {post} /api/v3/tasks/user Create a new task belonging to the user
  * @apiDescription Can be passed an object to create a single task or an array of objects to create multiple tasks.
  * @apiVersion 3.0.0
  * @apiName CreateUserTasks
@@ -73,13 +73,13 @@ api.createUserTasks = {
 };
 
 /**
- * @api {post} /api/v3/tasks/challenge/:challengeId Create a new task belonging to a challenge.
+ * @api {post} /api/v3/tasks/challenge/:challengeId Create a new task belonging to a challenge
  * @apiDescription Can be passed an object to create a single task or an array of objects to create multiple tasks.
  * @apiVersion 3.0.0
  * @apiName CreateChallengeTasks
  * @apiGroup Task
  *
- * @apiParam {UUID} challengeId The id of the challenge the new task(s) will belong to.
+ * @apiParam {UUID} challengeId The id of the challenge the new task(s) will belong to
  *
  * @apiSuccess data An object if a single task was created, otherwise an array of tasks
  */
@@ -171,7 +171,7 @@ async function _getTasks (req, res, user, challenge) {
  * @apiName GetUserTasks
  * @apiGroup Task
  *
- * @apiParam {string="habits","dailys","todos","rewards","completedTodos"} type Optional query parameter to return just a type of tasks. By default all types will be returned except completed todos that requested separately.
+ * @apiParam {string="habits","dailys","todos","rewards","completedTodos"} type Optional query parameter to return just a type of tasks. By default all types will be returned except completed todos that must be requested separately.
  *
  * @apiSuccess {Array} data An array of tasks
  */
@@ -197,7 +197,7 @@ api.getUserTasks = {
  * @apiName GetChallengeTasks
  * @apiGroup Task
  *
- * @apiParam {UUID} challengeId The id of the challenge from which to retrieve the tasks.
+ * @apiParam {UUID} challengeId The id of the challenge from which to retrieve the tasks
  * @apiParam {string="habits","dailys","todos","rewards"} type Optional query parameter to return just a type of tasks
  *
  * @apiSuccess {Array} data An array of tasks
@@ -427,9 +427,9 @@ api.scoreTask = {
   },
 };
 
-// completed todos cannot be moved, they'll be returned ordered by date of completion
 /**
  * @api {post} /api/v3/tasks/:taskId/move/to/:position Move a task to a new position
+ * @apiDescription Note: completed To-Dos are not sortable, do not appear in user.tasksOrder.todos, and are ordered by date of completion.
  * @apiVersion 3.0.0
  * @apiName MoveTask
  * @apiGroup Task

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

@@ -142,7 +142,7 @@ let checkPreferencePurchase = (user, path, item) => {
 };
 
 /**
- * @api {put} /api/v3/user Update the user.
+ * @api {put} /api/v3/user Update the user
  * @apiDescription Example body: {'stats.hp':50, 'preferences.background': 'beach'}
  * @apiVersion 3.0.0
  * @apiName UserUpdate
@@ -305,13 +305,13 @@ api.getUserAnonymized = {
 const partyMembersFields = 'profile.name stats achievements items.special';
 
 /**
- * @api {post} /api/v3/user/class/cast/:spellId Cast a spell on a target.
+ * @api {post} /api/v3/user/class/cast/:spellId Cast a skill (spell) on a target
  * @apiVersion 3.0.0
  * @apiName UserCast
  * @apiGroup User
  *
- * @apiParam {string} spellId The spell to cast.
+ * @apiParam {string} spellId The skill to cast
- * @apiParam {UUID} targetId Optional query parameter, the id of the target when casting a spell on a party member or a task.
+ * @apiParam {UUID} targetId Optional query parameter, the id of the target when casting a skill on a party member or a task
  *
  * @apiSuccess data Will return the modified targets. For party members only the necessary fields will be populated. The user is always returned.
  */
@@ -443,7 +443,7 @@ api.castSpell = {
 };
 
 /**
- * @api {post} /api/v3/user/sleep Put the user in the inn.
+ * @api {post} /api/v3/user/sleep Make the user start / stop sleeping (resting in the Inn)
  * @apiVersion 3.0.0
  * @apiName UserSleep
  * @apiGroup User
@@ -463,7 +463,7 @@ api.sleep = {
 };
 
 /**
- * @api {post} /api/v3/user/allocate Allocate an attribute point.
+ * @api {post} /api/v3/user/allocate Allocate an attribute point
  * @apiVersion 3.0.0
  * @apiName UserAllocate
  * @apiGroup User
@@ -485,7 +485,8 @@ api.allocate = {
 };
 
 /**
- * @api {post} /api/v3/user/allocate-now Allocate all attribute points.
+ * @api {post} /api/v3/user/allocate-now Allocate all attribute points
+ * @apiDescription Uses the user's chosen automatic allocation method, or if none, assigns all to STR.
  * @apiVersion 3.0.0
  * @apiName UserAllocateNow
  * @apiGroup User
@@ -511,7 +512,7 @@ api.allocateNow = {
  * @apiName UserBuy
  * @apiGroup User
  *
- * @apiParam {string} key The item to buy.
+ * @apiParam {string} key The item to buy
  */
 api.buy = {
   method: 'POST',
@@ -526,12 +527,12 @@ api.buy = {
 };
 
 /**
- * @api {post} /user/buy-gear/:key Buy a piece of gear.
+ * @api {post} /user/buy-gear/:key Buy a piece of gear
  * @apiVersion 3.0.0
  * @apiName UserBuyGear
  * @apiGroup User
  *
- * @apiParam {string} key The item to buy.
+ * @apiParam {string} key The item to buy
  *
  * @apiSuccess {object} data.items user.items
  * @apiSuccess {object} data.flags user.flags
@@ -552,12 +553,12 @@ api.buyGear = {
 };
 
 /**
- * @api {post} /user/buy-armoire Buy an armoire item.
+ * @api {post} /user/buy-armoire Buy an armoire item
  * @apiVersion 3.0.0
  * @apiName UserBuyArmoire
  * @apiGroup User
  *
- * @apiParam {string} key The item to buy.
+ * @apiParam {string} key The item to buy
  *
  * @apiSuccess {object} data.items user.items
  * @apiSuccess {object} data.flags user.flags
@@ -600,12 +601,12 @@ api.buyPotion = {
 };
 
 /**
- * @api {post} /user/buy-mystery-set/:key Buy a mystery set.
+ * @api {post} /user/buy-mystery-set/:key Buy a mystery set
  * @apiVersion 3.0.0
  * @apiName UserBuyMysterySet
  * @apiGroup User
  *
- * @apiParam {string} key The mystery set to buy.
+ * @apiParam {string} key The mystery set to buy
  *
  * @apiSuccess {Object} data.items user.items
  * @apiSuccess {Object} data.purchasedPlanConsecutive user.purchased.plan.consecutive
@@ -624,12 +625,12 @@ api.buyMysterySet = {
 };
 
 /**
- * @api {post} /api/v3/user/buy-quest/:key Buy a quest with gold.
+ * @api {post} /api/v3/user/buy-quest/:key Buy a quest with gold
  * @apiVersion 3.0.0
  * @apiName UserBuyQuest
  * @apiGroup User
  *
- * @apiParam {string} key The quest spell to buy.
+ * @apiParam {string} key The quest scroll to buy
  *
  * @apiSuccess {Object} data `user.items.quests`
  * @apiSuccess {string} message Success message
@@ -647,12 +648,13 @@ api.buyQuest = {
 };
 
 /**
- * @api {post} /api/v3/user/buy-special-spell/:key Buy special spell.
+ * @api {post} /api/v3/user/buy-special-spell/:key Buy special "spell" item
+ * @apiDescription Includes gift cards (e.g., birthday card), and avatar Transformation Items and their antidotes (e.g., Snowball item and Salt reward).
  * @apiVersion 3.0.0
  * @apiName UserBuySpecialSpell
  * @apiGroup User
  *
- * @apiParam {string} key The special spell to buy.
+ * @apiParam {string} key The special item to buy. Must be one of the keys from "content.special", such as birthday, snowball, salt.
  *
  * @apiSuccess {Object} data.stats user.stats
  * @apiSuccess {Object} data.items user.items
@@ -671,13 +673,13 @@ api.buySpecialSpell = {
 };
 
 /**
- * @api {post} /api/v3/user/hatch/:egg/:hatchingPotion Hatch a pet.
+ * @api {post} /api/v3/user/hatch/:egg/:hatchingPotion Hatch a pet
  * @apiVersion 3.0.0
  * @apiName UserHatch
  * @apiGroup User
  *
- * @apiParam {string} egg The egg to use.
+ * @apiParam {string} egg The egg to use
- * @apiParam {string} hatchingPotion The hatching potion to use.
+ * @apiParam {string} hatchingPotion The hatching potion to use
  *
  * @apiSuccess {Object} data user.items
  * @apiSuccess {string} message
@@ -743,13 +745,13 @@ api.feed = {
 };
 
 /**
-* @api {post} /api/v3/user/change-class Change class.
+* @api {post} /api/v3/user/change-class Change class
 * @apiDescription User must be at least level 10. If ?class is defined and user.flags.classSelected is false it'll change the class. If user.preferences.disableClasses it'll enable classes, otherwise it sets user.flags.classSelected to false (costs 3 gems)
 * @apiVersion 3.0.0
 * @apiName UserChangeClass
 * @apiGroup User
 *
-* @apiParam {string} class Query parameter - ?class={warrior|rogue|wizard|healer}.
+* @apiParam {string} class Query parameter - ?class={warrior|rogue|wizard|healer}
 *
 * @apiSuccess {object} data.flags user.flags
 * @apiSuccess {object} data.stats user.stats
@@ -769,7 +771,7 @@ api.changeClass = {
 };
 
 /**
-* @api {post} /api/v3/user/disable-classes Disable classes.
+* @api {post} /api/v3/user/disable-classes Disable classes
 * @apiVersion 3.0.0
 * @apiName UserDisableClasses
 * @apiGroup User
@@ -791,13 +793,13 @@ api.disableClasses = {
 };
 
 /**
-* @api {post} /api/v3/user/purchase/:type/:key Purchase Gem Items.
+* @api {post} /api/v3/user/purchase/:type/:key Purchase Gem or Gem-purchasable item
 * @apiVersion 3.0.0
 * @apiName UserPurchase
 * @apiGroup User
 *
-* @apiParam {string} type Type of item to purchase. Must be one of: gem, gems, eggs, hatchingPotions, food, quests or gear
+* @apiParam {string} type Type of item to purchase. Must be one of: gems, eggs, hatchingPotions, food, quests, or gear
-* @apiParam {string} key Item's key
+* @apiParam {string} key Item's key (use "gem" for purchasing gems)
 *
 * @apiSuccess {object} data.items user.items
 * @apiSuccess {number} data.balance user.balance
@@ -816,7 +818,7 @@ api.purchase = {
 };
 
 /**
-* @api {post} /api/v3/user/purchase-hourglass/:type/:key Purchase Hourglass.
+* @api {post} /api/v3/user/purchase-hourglass/:type/:key Purchase Hourglass-purchasable item
 * @apiVersion 3.0.0
 * @apiName UserPurchaseHourglass
 * @apiGroup User
@@ -841,7 +843,7 @@ api.userPurchaseHourglass = {
 };
 
 /**
-* @api {post} /api/v3/user/read-card/:cardType Reads a card.
+* @api {post} /api/v3/user/read-card/:cardType Reads a card
 * @apiVersion 3.0.0
 * @apiName UserReadCard
 * @apiGroup User
@@ -865,7 +867,7 @@ api.readCard = {
 };
 
 /**
-* @api {post} /api/v3/user/open-mystery-item Open the mystery item.
+* @api {post} /api/v3/user/open-mystery-item Open the Mystery Item box
 * @apiVersion 3.0.0
 * @apiName UserOpenMysteryItem
 * @apiGroup User
@@ -955,7 +957,7 @@ api.deleteWebhook = {
 };
 
 
-/* @api {post} /api/v3/user/release-pets Releases pets.
+/* @api {post} /api/v3/user/release-pets Release pets
 * @apiVersion 3.0.0
 * @apiName UserReleasePets
 * @apiGroup User
@@ -976,7 +978,7 @@ api.userReleasePets = {
 };
 
 /*
-* @api {post} /api/v3/user/release-both Releases Pets and Mounts and grants Triad Bingo.
+* @api {post} /api/v3/user/release-both Release pets and mounts and grants Triad Bingo
 * @apiVersion 3.0.0
 * @apiName UserReleaseBoth
 * @apiGroup User
@@ -999,7 +1001,7 @@ api.userReleaseBoth = {
 };
 
 /*
-* @api {post} /api/v3/user/release-mounts Released mounts.
+* @api {post} /api/v3/user/release-mounts Release mounts
 * @apiVersion 3.0.0
 * @apiName UserReleaseMounts
 * @apiGroup User
@@ -1020,12 +1022,12 @@ api.userReleaseMounts = {
 };
 
 /*
-* @api {post} /api/v3/user/sell/:type/:key Sells a gold item owned by the user.
+* @api {post} /api/v3/user/sell/:type/:key Sell a gold-sellable item owned by the user
 * @apiVersion 3.0.0
 * @apiName UserSell
 * @apiGroup User
 *
-* @apiParam {string} type The type of item to sell. Acceptable types are eggs, hatchingPotions, food
+* @apiParam {string} type The type of item to sell. Must be one of: eggs, hatchingPotions, or food
 * @apiParam {string} key The key of the item
 *
 * @apiSuccess {Object} data.stats
@@ -1045,7 +1047,7 @@ api.userSell = {
 };
 
 /*
-* @api {post} /api/v3/user/unlock Unlocks items by purchase.
+* @api {post} /api/v3/user/unlock Unlock item or set of items by purchase
 * @apiVersion 3.0.0
 * @apiName UserUnlock
 * @apiGroup User
@@ -1053,9 +1055,9 @@ api.userSell = {
 * @apiParam {string} path Query parameter. The path to unlock
 *
 * @apiSuccess {Object} data.purchased
-* @apiSuccess {Object} data.items`
+* @apiSuccess {Object} data.items
-* @apiSuccess {Object} data.preferences`
+* @apiSuccess {Object} data.preferences
-* @apiSuccess {string} message`
+* @apiSuccess {string} message
 */
 api.userUnlock = {
   method: 'POST',
@@ -1070,7 +1072,7 @@ api.userUnlock = {
 };
 
 /**
-* @api {post} /api/v3/user/revive Revives user from death.
+* @api {post} /api/v3/user/revive Revive user from death
 * @apiVersion 3.0.0
 * @apiName UserRevive
 * @apiGroup User
@@ -1128,7 +1130,8 @@ api.userRebirth = {
 };
 
 /**
- * @api {post} /api/v3/user/block/:uuid Blocks and unblocks a user
+ * @api {post} /api/v3/user/block/:uuid Block and unblock a user
+ * @apiDescription Must be an admin to make this request.
  * @apiVersion 3.0.0
  * @apiName BlockUser
  * @apiGroup User
@@ -1212,7 +1215,7 @@ api.markPmsRead = {
 };
 
 /*
-* @api {post} /api/v3/user/reroll Rerolls a user.
+* @api {post} /api/v3/user/reroll Reroll a user using the Fortify Potion
 * @apiVersion 3.0.0
 * @apiName UserReroll
 * @apiGroup User
@@ -1248,7 +1251,7 @@ api.userReroll = {
 };
 
 /*
-* @api {post} /api/v3/user/addPushDevice Adds a push device to a user.
+* @api {post} /api/v3/user/addPushDevice Add a push device to a user
 * @apiVersion 3.0.0
 * @apiName UserAddPushDevice
 * @apiGroup User
@@ -1274,7 +1277,7 @@ api.userAddPushDevice = {
 };
 
 /*
-* @api {post} /api/v3/user/reset Resets a user.
+* @api {post} /api/v3/user/reset Reset user
 * @apiVersion 3.0.0
 * @apiName UserReset
 * @apiGroup User

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

@@ -26,8 +26,8 @@ const BASE_URL = nconf.get('BASE_URL');
 let api = {};
 
 /**
- * @api {get} /export/history.csv Export user tasks history in CSV format.
+ * @api {get} /export/history.csv Export user tasks history in CSV format
- * @apiDescription History is only available for habits and dailys so todos and rewards won't be included NOTE: Part of the private API that may change at any time.
+ * @apiDescription History is only available for habits and dailys so todos and rewards won't be included. NOTE: Part of the private API that may change at any time.
  * @apiVersion 3.0.0
  * @apiName ExportUserHistory
  * @apiGroup DataExport
@@ -94,7 +94,7 @@ async function _getUserDataForExport (user) {
 }
 
 /**
- * @api {get} /export/userdata.json Export user data in JSON format.
+ * @api {get} /export/userdata.json Export user data in JSON format
  * @apiVersion 3.0.0
  * @apiName ExportUserDataJson
  * @apiGroup DataExport