Refactor api description with @apiParam groups to make it more explicit (#8919)

* Refactor api description for auth.js with @apiParam groups

* Refactor apiDoc toward better consistency

* Fix missing groups for get requests

* Fix missing groups for other request methods

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

@@ -81,10 +81,10 @@ function hasBackupAuth (user, networkToRemove) {
  * @apiName UserRegisterLocal
  * @apiGroup User
  *
- * @apiParam {String} username Body parameter - Username of the new user
+ * @apiParam (Body) {String} username Username of the new user
- * @apiParam {String} email Body parameter - Email address of the new user
+ * @apiParam (Body) {String} email Email address of the new user
- * @apiParam {String} password Body parameter - Password for the new user
+ * @apiParam (Body) {String} password Password for the new user
- * @apiParam {String} confirmPassword Body parameter - Password confirmation
+ * @apiParam (Body) {String} confirmPassword Password confirmation
  *
  * @apiSuccess {Object} data The user object, if local auth was just attached to a social user then only user.auth.local
  */
@@ -206,8 +206,8 @@ function _loginRes (user, req, res) {
  * @apiName UserLoginLocal
  * @apiGroup User
  *
- * @apiParam {String} username Body parameter - Username or email of the user
+ * @apiParam (Body) {String} username Username or email of the user
- * @apiParam {String} password Body parameter - The user's password
+ * @apiParam (Body) {String} password The user's password
  *
  * @apiSuccess {String} data._id The user's unique identifier
  * @apiSuccess {String} data.apiToken The user's api token that must be used to authenticate requests.
@@ -368,8 +368,8 @@ api.loginSocial = {
  * @apiName UserAuthPusher
  * @apiGroup User
  *
- * @apiParam {String} socket_id Body parameter
+ * @apiParam (Body) {String} socket_id A unique identifier for the specific client connection to Pusher
- * @apiParam {String} channel_name Body parameter
+ * @apiParam (Body) {String} channel_name The name of the channel being subscribed to
  *
  * @apiSuccess {String} auth The authentication token
  */
@@ -436,8 +436,8 @@ api.pusherAuth = {
  * @apiName UpdateUsername
  * @apiGroup User
  *
- * @apiParam {String} password Body parameter - The current user password
+ * @apiParam (Body) {String} password The current user password
- * @apiParam {String} username Body parameter - The new username
+ * @apiParam (Body) {String} username The new username
 
  * @apiSuccess {String} data.username The new username
  **/
@@ -489,9 +489,9 @@ api.updateUsername = {
  * @apiName UpdatePassword
  * @apiGroup User
  *
- * @apiParam {String} password Body parameter - The old password
+ * @apiParam (Body) {String} password The old password
- * @apiParam {String} newPassword Body parameter - The new password
+ * @apiParam (Body) {String} newPassword The new password
- * @apiParam {String} confirmPassword Body parameter - New password confirmation
+ * @apiParam (Body) {String} confirmPassword New password confirmation
  *
  * @apiSuccess {Object} data An empty object
  **/
@@ -543,7 +543,7 @@ api.updatePassword = {
  * @apiName ResetPassword
  * @apiGroup User
  *
- * @apiParam {String} email Body parameter - The email address of the user
+ * @apiParam (Body) {String} email The email address of the user
  *
  * @apiSuccess {String} message The localized success message
  **/
@@ -600,8 +600,8 @@ api.resetPassword = {
  * @apiName UpdateEmail
  * @apiGroup User
  *
- * @apiParam {String} Body parameter - newEmail The new email address.
+ * @apiParam (Body) {String} newEmail The new email address.
- * @apiParam {String} Body parameter - password The user password.
+ * @apiParam (Body) {String} password The user password.
  *
  * @apiSuccess {String} data.email The updated email address
  */

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

@@ -66,7 +66,7 @@ async function saveContentToDisk (language, content) {
  * @apiName ContentGet
  * @apiGroup Content
  *
- * @apiParam {String="bg","cs","da","de","en","en@pirate","en_GB","es","es_419","fr","he","hu","id","it","ja","nl","pl","pt","pt_BR","ro","ru","sk","sr","sv","uk","zh","zh_TW"} [language=en]  Query parameter, the  language code used for the items' strings. If the authenticated user makes the request, the content will return with the user's configured language.
+ * @apiParam (Query) {String="bg","cs","da","de","en","en@pirate","en_GB","es","es_419","fr","he","hu","id","it","ja","nl","pl","pt","pt_BR","ro","ru","sk","sr","sv","uk","zh","zh_TW"} [language=en]  Language code used for the items' strings. If the authenticated user makes the request, the content will return with the user's configured language.
  *
  * @apiSuccess {Object} data Various data about the content of Habitica. The content route
  * contains many keys, but the data listed below are the recomended data to use.

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

@@ -115,14 +115,14 @@ api.makeAdmin = {
  * @apiGroup Development
  * @apiPermission Developers
  *
- * @apiParam {Object} gear Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#L243">gear.owned</a></code> object.
+ * @apiParam (Body) {Object} gear Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#L243">gear.owned</a></code> object.
- * @apiParam {Object} special Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#272">special</a></code> object.
+ * @apiParam (Body) {Object} special Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#272">special</a></code> object.
- * @apiParam {Object} pets Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#296">pets</a></code> object.
+ * @apiParam (Body) {Object} pets Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#296">pets</a></code> object.
- * @apiParam {Object} mounts Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#329">mounts</a></code> object.
+ * @apiParam (Body) {Object} mounts Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#329">mounts</a></code> object.
- * @apiParam {Object} eggs Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#310">eggs</a></code> object.
+ * @apiParam (Body) {Object} eggs Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#310">eggs</a></code> object.
- * @apiParam {Object} hatchingPotions Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#316">hatchingPotions</a></code> object.
+ * @apiParam (Body) {Object} hatchingPotions Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#316">hatchingPotions</a></code> object.
- * @apiParam {Object} food Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#322">food</a></code> object.
+ * @apiParam (Body) {Object} food Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#322">food</a></code> object.
- * @apiParam {Object} quests Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#344">quests</a></code> object.
+ * @apiParam (Body) {Object} quests Object to replace user's <code><a href="https://github.com/HabitRPG/habitica/blob/develop/website/server/models/user/schema.js#344">quests</a></code> object.
  * @apiSuccess {Object} data An empty Object
  */
 api.modifyInventory = {

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

@@ -263,9 +263,9 @@ api.createGroupPlan = {
  * @apiName GetGroups
  * @apiGroup Group
  *
- * @apiParam {String} type The type of groups to retrieve. Must be a query string representing a list of values like 'tavern,party'. Possible values are party, guilds, privateGuilds, publicGuilds, tavern
+ * @apiParam (Query) {String} type The type of groups to retrieve. Must be a query string representing a list of values like 'tavern,party'. Possible values are party, guilds, privateGuilds, publicGuilds, tavern
- * @apiParam {String="true","false"} [paginate] Public guilds support pagination. When true guilds are returned in groups of 30
+ * @apiParam (Query) {String="true","false"} [paginate] Public guilds support pagination. When true guilds are returned in groups of 30
- * @apiParam {Number} [page] When pagination is enabled for public guilds this parameter can be used to specify the page number (the initial page is number 0 and not required)
+ * @apiParam (Query) {Number} [page] When pagination is enabled for public guilds this parameter can be used to specify the page number (the initial page is number 0 and not required)
  *
  * @apiParamExample {json} Private Guilds, Tavern:
  *     {
@@ -691,7 +691,7 @@ function _removeMessagesFromMember (member, groupId) {
  * @apiName LeaveGroup
  * @apiGroup Group
  *
- * @apiParam {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted)
+ * @apiParam (Path) {String} groupId The group _id ('party' for the user party and 'habitrpg' for tavern are accepted)
  * @apiParam (Query) {String="remove-all","keep-all"} keep=keep-all Whether or not to keep challenge tasks belonging to the group being left.
  * @apiParam (Body) {String="remain-in-challenges","leave-challenges"} [keepChallenges=leave-challenges] Whether or not to remain in the challenges of the group being left.
  *

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

@@ -142,7 +142,7 @@ const heroAdminFields = 'contributor balance profile.name purchased items auth f
 
 /**
  * @api {get} /api/v3/hall/heroes/:heroId Get any user ("hero") given the UUID
- * @apiParam {UUID} heroId user ID
+ * @apiParam (Path) {UUID} heroId user ID
  * @apiName GetHero
  * @apiGroup Hall
  * @apiPermission Admin
@@ -187,7 +187,7 @@ 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 any user ("hero")
- * @apiParam {UUID} heroId user ID
+ * @apiParam (Path) {UUID} heroId user ID
  * @apiName UpdateHero
  * @apiGroup Hall
  * @apiPermission Admin

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

@@ -29,7 +29,7 @@ let api = {};
  * @apiName GetMember
  * @apiGroup Member
  *
- * @apiParam {UUID} memberId The member's id
+ * @apiParam (Path) {UUID} memberId The member's id
  *
  * @apiSuccess {Object} data The member object
  *
@@ -281,11 +281,11 @@ function _getMembersForItem (type) {
  * @apiName GetMembersForGroup
  * @apiGroup Member
  *
- * @apiParam {UUID} groupId The group id
+ * @apiParam (Path) {UUID} groupId The group id
- * @apiParam {UUID} lastId Query parameter to specify the last member returned in a previous request to this route and get the next batch of results
+ * @apiParam (Query) {UUID} lastId Query parameter to specify the last member returned in a previous request to this route and get the next batch of results
- * @apiParam {boolean} includeAllPublicFields Query parameter available only when fetching a party. If === `true` then all public fields for members will be returned (like when making a request for a single member)
+ * @apiParam (Query) {Boolean} includeAllPublicFields Query parameter available only when fetching a party. If === `true` then all public fields for members will be returned (like when making a request for a single member)
  *
- * @apiSuccess {array} data An array of members, sorted by _id
+ * @apiSuccess {Array} data An array of members, sorted by _id
  * @apiUse ChallengeNotFound
  * @apiUse GroupNotFound
  */
@@ -302,8 +302,8 @@ api.getMembersForGroup = {
  * @apiName GetInvitesForGroup
  * @apiGroup Member
  *
- * @apiParam {UUID} groupId The group id
+ * @apiParam (Path) {UUID} groupId The group id
- * @apiParam {UUID} lastId Query parameter to specify the last invite returned in a previous request to this route and get the next batch of results
+ * @apiParam (Query) {UUID} lastId Query parameter to specify the last invite returned in a previous request to this route and get the next batch of results
  *
  * @apiSuccess {array} data An array of invites, sorted by _id
  *
@@ -327,11 +327,11 @@ api.getInvitesForGroup = {
  * @apiName GetMembersForChallenge
  * @apiGroup Member
  *
- * @apiParam {UUID} challengeId The challenge id
+ * @apiParam (Path) {UUID} challengeId The challenge id
- * @apiParam {UUID} lastId Query parameter to specify the last member returned in a previous request to this route and get the next batch of results
+ * @apiParam (Query) {UUID} lastId Query parameter to specify the last member returned in a previous request to this route and get the next batch of results
- * @apiParam {String} includeAllMembers BETA Query parameter - If 'true' all challenge members are returned
+ * @apiParam (Query) {String} includeAllMembers BETA Query parameter - If 'true' all challenge members are returned
 
- * @apiSuccess {array} data An array of members, sorted by _id
+ * @apiSuccess {Array} data An array of members, sorted by _id
  *
  * @apiUse ChallengeNotFound
  * @apiUse GroupNotFound
@@ -348,8 +348,8 @@ api.getMembersForChallenge = {
  * @apiName GetChallengeMemberProgress
  * @apiGroup Member
  *
- * @apiParam {UUID} challengeId The challenge _id
+ * @apiParam (Path) {UUID} challengeId The challenge _id
- * @apiParam {UUID} member The member _id
+ * @apiParam (Path) {UUID} memberId The member _id
  *
  * @apiSuccess {Object} data Return an object with member _id, profile.name and a tasks object with the challenge tasks for the member
  *
@@ -404,8 +404,8 @@ api.getChallengeMemberProgress = {
  * @apiName GetObjectionsToInteraction
  * @apiGroup Member
  *
- * @apiParam {UUID} toUserId The user to interact with
+ * @apiParam (Path) {UUID} toUserId The user to interact with
- * @apiParam {String="send-private-message","transfer-gems"} interaction Name of the interaction to query
+ * @apiParam (Path) {String="send-private-message","transfer-gems"} interaction Name of the interaction to query
  *
  * @apiSuccess {Array} data Return an array of objections, if the interaction would be blocked; otherwise an empty array
  */
@@ -432,12 +432,12 @@ api.getObjectionsToInteraction = {
 };
 
 /**
- * @api {posts} /api/v3/members/send-private-message Send a private message to a member
+ * @api {post} /api/v3/members/send-private-message Send a private message to a member
  * @apiName SendPrivateMessage
  * @apiGroup Member
  *
- * @apiParam {String} message Body parameter - The message
+ * @apiParam (Body) {String} message Body parameter - The message
- * @apiParam {UUID} toUserId Body parameter - The user to contact
+ * @apiParam (Body) {UUID} toUserId Body parameter - The user to contact
  *
  * @apiSuccess {Object} data An empty Object
  *
@@ -488,13 +488,13 @@ api.sendPrivateMessage = {
 };
 
 /**
- * @api {posts} /api/v3/members/transfer-gems Send a gem gift to a member
+ * @api {post} /api/v3/members/transfer-gems Send a gem gift to a member
  * @apiName TransferGems
  * @apiGroup Member
  *
- * @apiParam {String} message Body parameter The message
+ * @apiParam (Body) {String} message The message
- * @apiParam {UUID} toUserId Body parameter The toUser _id
+ * @apiParam (Body) {UUID} toUserId The toUser _id
- * @apiParam {Integer} gemAmount Body parameter The number of gems to send
+ * @apiParam (Body) {Integer} gemAmount The number of gems to send
  *
  * @apiSuccess {Object} data An empty Object
  *

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

@@ -12,7 +12,7 @@ let api = {};
  * @apiName ReadNotification
  * @apiGroup Notification
  *
- * @apiParam {UUID} notificationId
+ * @apiParam (Path) {UUID} notificationId
  *
  * @apiSuccess {Object} data user.notifications
  */

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

@@ -12,8 +12,8 @@ let api = {};
  * @apiName UserAddPushDevice
  * @apiGroup User
  *
- * @apiParam {String} regId The id of the push device
+ * @apiParam (Body) {String} regId The id of the push device
- * @apiParam {String} type The type of push device
+ * @apiParam (Body) {String} type The type of push device
  *
  * @apiSuccess {Object} data List of push devices
  * @apiSuccess {String} message Success message
@@ -52,11 +52,11 @@ api.addPushDevice = {
 
 /**
  * @apiIgnore
- * @api {delete} /api/v3/user/push-devices remove a push device from a user
+ * @api {delete} /api/v3/user/push-devices/:regId remove a push device from a user
  * @apiName UserRemovePushDevice
  * @apiGroup User
  *
- * @apiParam {String} regId The id of the push device
+ * @apiParam (Path) {String} regId The id of the push device
  *
  * @apiSuccess {Object} data List of push devices
  * @apiSuccess {String} message Success message

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

@@ -43,8 +43,8 @@ let api = {};
  * @apiName InviteToQuest
  * @apiGroup Quest
  *
- * @apiParam {String} groupId The group _id (or 'party')
+ * @apiParam (Path) {String} groupId The group _id (or 'party')
- * @apiParam {String} questKey
+ * @apiParam (Path) {String} questKey
  *
  * @apiSuccess {Object} data Quest object
  *
@@ -158,7 +158,7 @@ api.inviteToQuest = {
  * @apiName AcceptQuest
  * @apiGroup Quest
  *
- * @apiParam {String} groupId The group _id (or 'party')
+ * @apiParam (Path) {String} groupId The group _id (or 'party')
  *
  * @apiSuccess {Object} data Quest Object
  *
@@ -217,7 +217,7 @@ api.acceptQuest = {
  * @apiName RejectQuest
  * @apiGroup Quest
  *
- * @apiParam {String} groupId The group _id (or 'party')
+ * @apiParam (Path) {String} groupId The group _id (or 'party')
  *
  * @apiSuccess {Object} data Quest Object
  *
@@ -277,7 +277,7 @@ api.rejectQuest = {
  * @apiName ForceQuestStart
  * @apiGroup Quest
  *
- * @apiParam {String} groupId The group _id (or 'party')
+ * @apiParam (Path) {String} groupId The group _id (or 'party')
  *
  * @apiSuccess {Object} data Quest Object
  *
@@ -335,7 +335,7 @@ api.forceStart = {
  * @apiName CancelQuest
  * @apiGroup Quest
  *
- * @apiParam {String} groupId The group _id (or 'party')
+ * @apiParam (Path) {String} groupId The group _id (or 'party')
  *
  * @apiSuccess {Object} data Quest Object
  *
@@ -389,7 +389,7 @@ api.cancelQuest = {
  * @apiName AbortQuest
  * @apiGroup Quest
  *
- * @apiParam {String} groupId The group _id (or 'party')
+ * @apiParam (Path) {String} groupId The group _id (or 'party')
  *
  * @apiSuccess {Object} data Quest Object
  *
@@ -451,7 +451,7 @@ api.abortQuest = {
  * @apiName LeaveQuest
  * @apiGroup Quest
  *
- * @apiParam {String} groupId The group _id (or 'party')
+ * @apiParam (Path) {String} groupId The group _id (or 'party')
  *
  * @apiSuccess {Object} data Quest Object
  *

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

@@ -25,7 +25,7 @@ let api = {};
  * @apiName CreateTag
  * @apiGroup Tag
  *
- * @apiParam (body) {string} name The name of the tag to be added.
+ * @apiParam (Body) {string} name The name of the tag to be added.
  *
  * @apiParamExample {json} Example body:
  * {"name":"practicetag"}
@@ -76,7 +76,7 @@ api.getTags = {
  * @apiName GetTag
  * @apiGroup Tag
  *
- * @apiParam {UUID} tagId The tag _id
+ * @apiParam (Path) {UUID} tagId The tag _id
  *
  * @apiSuccess {Object} data The tag object
  *
@@ -109,8 +109,8 @@ api.getTag = {
  * @apiName UpdateTag
  * @apiGroup Tag
  *
- * @apiParam {UUID} tagId The tag _id
+ * @apiParam (Path) {UUID} tagId The tag _id
- * @apiParam (body) {string} name The new name of the tag.
+ * @apiParam (Body) {string} name The new name of the tag.
  *
  * @apiParamExample {json} Example body:
  * {"name":"prac-tag"}
@@ -152,8 +152,8 @@ api.updateTag = {
  * @apiName ReorderTags
  * @apiGroup Tag
  *
- * @apiParam (body) {UUID} tagId Id of the tag to move
+ * @apiParam (Body) {UUID} tagId Id of the tag to move
- * @apiParam (body) {Number} to Position the tag is moving to
+ * @apiParam (Body) {Number} to Position the tag is moving to
  *
  * @apiParamExample {json} Example request:
  * {"tagId":"c6855fae-ca15-48af-a88b-86d0c65ead47","to":0}
@@ -194,7 +194,7 @@ api.reorderTags = {
  * @apiName DeleteTag
  * @apiGroup Tag
  *
- * @apiParam {UUID} tagId The tag _id
+ * @apiParam (Path) {UUID} tagId The tag _id
  *
  * @apiSuccess {Object} data An empty object
  *

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

@@ -57,24 +57,24 @@ let requiredGroupFields = '_id leader tasksOrder name';
  * @apiName CreateUserTasks
  * @apiGroup Task
  *
- * @apiParam (Body) {string} text The text to be displayed for the task
+ * @apiParam (Body) {String} text The text to be displayed for the task
- * @apiParam (Body) {string="habit","daily","todo","reward"} type Task type, options are: "habit", "daily", "todo", "reward".
+ * @apiParam (Body) {String="habit","daily","todo","reward"} type Task type, options are: "habit", "daily", "todo", "reward".
- * @apiParam (Body) {string[]} [tags] Array of UUIDs of tags
+ * @apiParam (Body) {String[]} [tags] Array of UUIDs of tags
- * @apiParam (Body) {string} [alias] Alias to assign to task
+ * @apiParam (Body) {String} [alias] Alias to assign to task
- * @apiParam (Body) {string="str","int","per","con"} [attribute] User's attribute to use, options are: "str", "int", "per", "con"
+ * @apiParam (Body) {String="str","int","per","con"} [attribute] User's attribute to use, options are: "str", "int", "per", "con"
- * @apiParam (Body) {boolean} [collapseChecklist=false] Determines if a checklist will be displayed
+ * @apiParam (Body) {Boolean} [collapseChecklist=false] Determines if a checklist will be displayed
- * @apiParam (Body) {string} [notes] Extra notes
+ * @apiParam (Body) {String} [notes] Extra notes
- * @apiParam (Body) {string} [date] Due date to be shown in task list. Only valid for type "todo."
+ * @apiParam (Body) {String} [date] Due date to be shown in task list. Only valid for type "todo."
- * @apiParam (Body) {number="0.1","1","1.5","2"} [priority=1] Difficulty, options are 0.1, 1, 1.5, 2; eqivalent of Trivial, Easy, Medium, Hard.
+ * @apiParam (Body) {Number="0.1","1","1.5","2"} [priority=1] Difficulty, options are 0.1, 1, 1.5, 2; eqivalent of Trivial, Easy, Medium, Hard.
- * @apiParam (Body) {string[]} [reminders] Array of reminders, each an object that must include: a UUID, startDate and time. For example {"id":"ed427623-9a69-4aac-9852-13deb9c190c3","startDate":"1/16/17","time":"1/16/17" }
+ * @apiParam (Body) {String[]} [reminders] Array of reminders, each an object that must include: a UUID, startDate and time. For example {"id":"ed427623-9a69-4aac-9852-13deb9c190c3","startDate":"1/16/17","time":"1/16/17" }
- * @apiParam (Body) {string="weekly","daily"} [frequency=weekly] Value "weekly" enables "On days of the week", value "daily" enables "EveryX Days". Only valid for type "daily".
+ * @apiParam (Body) {String="weekly","daily"} [frequency=weekly] Value "weekly" enables "On days of the week", value "daily" enables "EveryX Days". Only valid for type "daily".
- * @apiParam (Body) {string} [repeat=true] List of objects for days of the week,  Days that are true will be repeated upon. Only valid for type "daily". Any days not specified will be marked as true. Days are: su, m, t, w, th, f, s. Value of frequency must be "weekly". For example, to skip repeats on Mon and Fri: "repeat":{"f":false,"m":false}
+ * @apiParam (Body) {String} [repeat=true] List of objects for days of the week,  Days that are true will be repeated upon. Only valid for type "daily". Any days not specified will be marked as true. Days are: su, m, t, w, th, f, s. Value of frequency must be "weekly". For example, to skip repeats on Mon and Fri: "repeat":{"f":false,"m":false}
- * @apiParam (Body) {number} [everyX=1] Value of frequency must be "daily", the number of days until this daily task is available again.
+ * @apiParam (Body) {Number} [everyX=1] Value of frequency must be "daily", the number of days until this daily task is available again.
- * @apiParam (Body) {number} [streak=0] Number of days that the task has consecutively been checked off. Only valid for type "daily"
+ * @apiParam (Body) {Number} [streak=0] Number of days that the task has consecutively been checked off. Only valid for type "daily"
- * @apiParam (Body) {date} [startDate] Date when the task will first become available. Only valid for type "daily"
+ * @apiParam (Body) {Date} [startDate] Date when the task will first become available. Only valid for type "daily"
- * @apiParam (Body) {boolean} [up=true] Only valid for type "habit" If true, enables the "+" under "Directions/Action" for "Good habits"
+ * @apiParam (Body) {Boolean} [up=true] Only valid for type "habit" If true, enables the "+" under "Directions/Action" for "Good habits"
- * @apiParam (Body) {boolean} [down=true] Only valid for type "habit" If true, enables the "-" under "Directions/Action" for "Bad habits"
+ * @apiParam (Body) {Boolean} [down=true] Only valid for type "habit" If true, enables the "-" under "Directions/Action" for "Bad habits"
- * @apiParam (Body) {number} [value=0] Only valid for type "reward." The cost in gold of the reward
+ * @apiParam (Body) {Number} [value=0] Only valid for type "reward." The cost in gold of the reward
  *
  * @apiParamExample {json} Request-Example:
  *     {
@@ -180,25 +180,25 @@ api.createUserTasks = {
  * @apiName CreateChallengeTasks
  * @apiGroup Task
  *
- * @apiParam {UUID} challengeId The id of the challenge the new task(s) will belong to
+ * @apiParam (Path) {UUID} challengeId The id of the challenge the new task(s) will belong to
  *
- * @apiParam (Body) {string} text The text to be displayed for the task
+ * @apiParam (Body) {String} text The text to be displayed for the task
- * @apiParam (Body) {string="habit","daily","todo","reward"} type Task type, options are: "habit", "daily", "todo", "reward".
+ * @apiParam (Body) {String="habit","daily","todo","reward"} type Task type, options are: "habit", "daily", "todo", "reward".
- * @apiParam (Body) {string} [alias] Alias to assign to task
+ * @apiParam (Body) {String} [alias] Alias to assign to task
- * @apiParam (Body) {string="str","int","per","con"} [attribute] User's attribute to use, options are: "str", "int", "per", "con"
+ * @apiParam (Body) {String="str","int","per","con"} [attribute] User's attribute to use, options are: "str", "int", "per", "con"
- * @apiParam (Body) {boolean} [collapseChecklist=false] Determines if a checklist will be displayed
+ * @apiParam (Body) {Boolean} [collapseChecklist=false] Determines if a checklist will be displayed
- * @apiParam (Body) {string} [notes] Extra notes
+ * @apiParam (Body) {String} [notes] Extra notes
- * @apiParam (Body) {string} [date] Due date to be shown in task list. Only valid for type "todo."
+ * @apiParam (Body) {String} [date] Due date to be shown in task list. Only valid for type "todo."
- * @apiParam (Body) {number="0.1","1","1.5","2"} [priority=1] Difficulty, options are 0.1, 1, 1.5, 2; eqivalent of Trivial, Easy, Medium, Hard.
+ * @apiParam (Body) {Number="0.1","1","1.5","2"} [priority=1] Difficulty, options are 0.1, 1, 1.5, 2; eqivalent of Trivial, Easy, Medium, Hard.
- * @apiParam (Body) {string[]} [reminders] Array of reminders, each an object that must include: a UUID, startDate and time. For example {"id":"ed427623-9a69-4aac-9852-13deb9c190c3","startDate":"1/16/17","time":"1/16/17" }
+ * @apiParam (Body) {String[]} [reminders] Array of reminders, each an object that must include: a UUID, startDate and time. For example {"id":"ed427623-9a69-4aac-9852-13deb9c190c3","startDate":"1/16/17","time":"1/16/17" }
- * @apiParam (Body) {string="weekly","daily"} [frequency=weekly] Value "weekly" enables "On days of the week", value "daily" enables "EveryX Days". Only valid for type "daily".
+ * @apiParam (Body) {String="weekly","daily"} [frequency=weekly] Value "weekly" enables "On days of the week", value "daily" enables "EveryX Days". Only valid for type "daily".
- * @apiParam (Body) {string} [repeat=true] List of objects for days of the week,  Days that are true will be repeated upon. Only valid for type "daily". Any days not specified will be marked as true. Days are: su, m, t, w, th, f, s. Value of frequency must be "weekly". For example, to skip repeats on Mon and Fri: "repeat":{"f":false,"m":false}
+ * @apiParam (Body) {String} [repeat=true] List of objects for days of the week,  Days that are true will be repeated upon. Only valid for type "daily". Any days not specified will be marked as true. Days are: su, m, t, w, th, f, s. Value of frequency must be "weekly". For example, to skip repeats on Mon and Fri: "repeat":{"f":false,"m":false}
- * @apiParam (Body) {number} [everyX=1] Value of frequency must be "daily", the number of days until this daily task is available again.
+ * @apiParam (Body) {Number} [everyX=1] Value of frequency must be "daily", the number of days until this daily task is available again.
- * @apiParam (Body) {number} [streak=0] Number of days that the task has consecutively been checked off. Only valid for type "daily"
+ * @apiParam (Body) {Number} [streak=0] Number of days that the task has consecutively been checked off. Only valid for type "daily"
- * @apiParam (Body) {date} [startDate] Date when the task will first become available. Only valid for type "daily"
+ * @apiParam (Body) {Date} [startDate] Date when the task will first become available. Only valid for type "daily"
- * @apiParam (Body) {boolean} [up=true] Only valid for type "habit" If true, enables the "+" under "Directions/Action" for "Good habits"
+ * @apiParam (Body) {Boolean} [up=true] Only valid for type "habit" If true, enables the "+" under "Directions/Action" for "Good habits"
- * @apiParam (Body) {boolean} [down=true] Only valid for type "habit" If true, enables the "-" under "Directions/Action" for "Bad habits"
+ * @apiParam (Body) {Boolean} [down=true] Only valid for type "habit" If true, enables the "-" under "Directions/Action" for "Bad habits"
- * @apiParam (Body) {number} [value=0] Only valid for type "reward." The cost in gold of the reward
+ * @apiParam (Body) {Number} [value=0] Only valid for type "reward." The cost in gold of the reward
  *
  * @apiParamExample {json} Request-Example:
  * {"type":"todo","text":"Test API Params"}
@@ -249,7 +249,7 @@ api.createChallengeTasks = {
  * @apiName GetUserTasks
  * @apiGroup Task
  *
- * @apiParam (URL) {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. The "completedTodos" type returns only the 30 most recently completed.
+ * @apiParam (Query) {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. The "completedTodos" type returns only the 30 most recently completed.
  *
  * @apiSuccess {Array} data An array of tasks
  *
@@ -284,8 +284,8 @@ api.getUserTasks = {
  * @apiName GetChallengeTasks
  * @apiGroup Task
  *
- * @apiParam {UUID} challengeId The id of the challenge from which to retrieve the tasks
+ * @apiParam (Path) {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
+ * @apiParam (Query) {String="habits","dailys","todos","rewards"} [type] Query parameter to return just a type of tasks
  *
  * @apiExample {curl} Example use:
  * curl -i https://habitica.com/api/v3/tasks/challenge/f23c12f2-5830-4f15-9c36-e17fd729a812
@@ -335,7 +335,7 @@ api.getChallengeTasks = {
  * @apiName GetTask
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id or alias
+ * @apiParam (Path) {String} taskId The task _id or alias
  *
  * @apiExample {curl} Example use:
  * curl -i https://habitica.com/api/v3/tasks/54a81d23-529c-4daa-a6f7-c5c6e7e84936
@@ -376,23 +376,23 @@ api.getTask = {
  * @apiName UpdateTask
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id or alias
+ * @apiParam (Path) {String} taskId The task _id or alias
  *
- * @apiParam (Body) {string} [text] The text to be displayed for the task
+ * @apiParam (Body) {String} [text] The text to be displayed for the task
- * @apiParam (Body) {string="str","int","per","con"} [attribute] User's attribute to use, options are: "str", "int", "per", "con"
+ * @apiParam (Body) {String="str","int","per","con"} [attribute] User's attribute to use, options are: "str", "int", "per", "con"
- * @apiParam (Body) {boolean} [collapseChecklist=false] Determines if a checklist will be displayed
+ * @apiParam (Body) {Boolean} [collapseChecklist=false] Determines if a checklist will be displayed
- * @apiParam (Body) {string} [notes] Extra notes
+ * @apiParam (Body) {String} [notes] Extra notes
- * @apiParam (Body) {string} [date] Due date to be shown in task list. Only valid for type "todo."
+ * @apiParam (Body) {String} [date] Due date to be shown in task list. Only valid for type "todo."
- * @apiParam (Body) {number="0.1","1","1.5","2"} [priority=1] Difficulty, options are 0.1, 1, 1.5, 2; eqivalent of Trivial, Easy, Medium, Hard.
+ * @apiParam (Body) {Number="0.1","1","1.5","2"} [priority=1] Difficulty, options are 0.1, 1, 1.5, 2; eqivalent of Trivial, Easy, Medium, Hard.
- * @apiParam (Body) {string[]} [reminders] Array of reminders, each an object that must include: a UUID, startDate and time.
+ * @apiParam (Body) {String[]} [reminders] Array of reminders, each an object that must include: a UUID, startDate and time.
- * @apiParam (Body) {string="weekly","daily"} [frequency=weekly] Value "weekly" enables "On days of the week", value "daily" enables "EveryX Days". Only valid for type "daily".
+ * @apiParam (Body) {String="weekly","daily"} [frequency=weekly] Value "weekly" enables "On days of the week", value "daily" enables "EveryX Days". Only valid for type "daily".
- * @apiParam (Body) {string} [repeat=true] List of objects for days of the week,  Days that are true will be repeated upon. Only valid for type "daily". Any days not specified will be marked as true. Days are: su, m, t, w, th, f, s. Value of frequency must be "weekly". For example, to skip repeats on Mon and Fri: "repeat":{"f":false,"m":false}
+ * @apiParam (Body) {String} [repeat=true] List of objects for days of the week,  Days that are true will be repeated upon. Only valid for type "daily". Any days not specified will be marked as true. Days are: su, m, t, w, th, f, s. Value of frequency must be "weekly". For example, to skip repeats on Mon and Fri: "repeat":{"f":false,"m":false}
- * @apiParam (Body) {number} [everyX=1] Value of frequency must be "daily", the number of days until this daily task is available again.
+ * @apiParam (Body) {Number} [everyX=1] Value of frequency must be "daily", the number of days until this daily task is available again.
- * @apiParam (Body) {number} [streak=0] Number of days that the task has consecutively been checked off. Only valid for type "daily"
+ * @apiParam (Body) {Number} [streak=0] Number of days that the task has consecutively been checked off. Only valid for type "daily"
- * @apiParam (Body) {date} [startDate] Date when the task will first become available. Only valid for type "daily"
+ * @apiParam (Body) {Date} [startDate] Date when the task will first become available. Only valid for type "daily"
- * @apiParam (Body) {boolean} [up=true] Only valid for type "habit" If true, enables the "+" under "Directions/Action" for "Good habits"
+ * @apiParam (Body) {Boolean} [up=true] Only valid for type "habit" If true, enables the "+" under "Directions/Action" for "Good habits"
- * @apiParam (Body) {boolean} [down=true] Only valid for type "habit" If true, enables the "-" under "Directions/Action" for "Bad habits"
+ * @apiParam (Body) {Boolean} [down=true] Only valid for type "habit" If true, enables the "-" under "Directions/Action" for "Bad habits"
- * @apiParam (Body) {number} [value=0] Only valid for type "reward." The cost in gold of the reward
+ * @apiParam (Body) {Number} [value=0] Only valid for type "reward." The cost in gold of the reward
  *
  * @apiParamExample {json} Request-Example:
  * {"notes":"This will be replace the notes, anything not specified will remain the same"}
@@ -495,9 +495,9 @@ api.updateTask = {
  * @apiName ScoreTask
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id or alias
+ * @apiParam (Path) {String} taskId The task _id or alias
- * @apiParam {String="up","down"} direction The direction for scoring the task
+ * @apiParam (Path) {String="up","down"} direction The direction for scoring the task
- * @apiParam {String} scoreNotes Notes explaining the scoring
+ * @apiParam (Body) {String} scoreNotes Notes explaining the scoring
  *
  * @apiExample {json} Example call:
  * curl -X "POST" https://habitica.com/api/v3/tasks/test-api-params/score/up
@@ -656,8 +656,8 @@ api.scoreTask = {
  * @apiName MoveTask
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id or alias
+ * @apiParam (Path) {String} taskId The task _id or alias
- * @apiParam {Number} position Query parameter - Where to move the task. 0 = top of the list. -1 = bottom of the list.  (-1 means push to bottom). First position is 0
+ * @apiParam (Path) {Number} position Where to move the task. 0 = top of the list. -1 = bottom of the list.  (-1 means push to bottom). First position is 0
  *
  * @apiSuccess {Array} data The new tasks order for the specific type that the taskID belongs to.
  *
@@ -699,9 +699,9 @@ api.moveTask = {
  * @apiName AddChecklistItem
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id or alias
+ * @apiParam (Path) {String} taskId The task _id or alias
  *
- * @apiParam (Body) {string} text The text of the checklist item
+ * @apiParam (Body) {String} text The text of the checklist item
  *
  * @apiParamExample {json} Example body data:
  * {"text":"Do this subtask"}
@@ -765,8 +765,8 @@ api.addChecklistItem = {
  * @apiName ScoreChecklistItem
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id or alias
+ * @apiParam (Path) {String} taskId The task _id or alias
- * @apiParam {UUID} itemId The checklist item _id
+ * @apiParam (Path) {UUID} itemId The checklist item _id
  *
  * @apiSuccess {Object} data The updated task
  *
@@ -807,10 +807,10 @@ api.scoreCheckListItem = {
  * @apiName UpdateChecklistItem
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id or alias
+ * @apiParam (Path) {String} taskId The task _id or alias
- * @apiParam {UUID} itemId The checklist item _id
+ * @apiParam (Path) {UUID} itemId The checklist item _id
  *
- * @apiParam (body) {string} text The text that will replace the current checkitem text.
+ * @apiParam (body) {String} text The text that will replace the current checkitem text.
  *
  * @apiParamExample {json} Example body:
  * {"text":"Czech 1"}
@@ -874,8 +874,8 @@ api.updateChecklistItem = {
  * @apiName RemoveChecklistItem
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id or alias
+ * @apiParam (Path) {String} taskId The task _id or alias
- * @apiParam {UUID} itemId The checklist item _id
+ * @apiParam (Path) {UUID} itemId The checklist item _id
  *
  * @apiSuccess {Object} data The updated task
  *
@@ -937,8 +937,8 @@ api.removeChecklistItem = {
  * @apiName AddTagToTask
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id or alias
+ * @apiParam (Path) {String} taskId The task _id or alias
- * @apiParam {UUID} tagId The tag id
+ * @apiParam (Path) {UUID} tagId The tag id
  *
  * @apiSuccess {Object} data The updated task
  *
@@ -984,8 +984,8 @@ api.addTagToTask = {
  * @apiName RemoveTagFromTask
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id or alias
+ * @apiParam (Path) {String} taskId The task _id or alias
- * @apiParam {UUID} tagId The tag id
+ * @apiParam (Path) {UUID} tagId The tag id
  *
  * @apiExample {curl} Example use:
  * curl -X "DELETE" https://habitica.com/api/v3/tasks/test-api-params/tags/3d5d324d-a042-4d5f-872e-0553e228553e
@@ -1029,8 +1029,8 @@ api.removeTagFromTask = {
  * @apiName UnlinkAllTasks
  * @apiGroup Task
  *
- * @apiParam {UUID} challengeId The challenge _id
+ * @apiParam (Path) {UUID} challengeId The challenge _id
- * @apiParam {String} keep Query parameter - keep-all or remove-all
+ * @apiParam (Query) {String='keep-all','remove-all'} keep Specifies if tasks should be kept(keep-all) or removed(remove-all) after the unlink
  *
  * @apiExample {curl}
  * curl -X "POST" https://habitica.com/api/v3/tasks/unlink-all/f23c12f2-5830-4f15-9c36-e17fd729a812?keep=remove-all
@@ -1099,8 +1099,8 @@ api.unlinkAllTasks = {
  * @apiName UnlinkOneTask
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id or alias
+ * @apiParam (Path) {String} taskId The task _id or alias
- * @apiParam {String} keep Query parameter - keep or remove
+ * @apiParam (Query) {String='keep','remove'} keep  Specifies if the task should be kept(keep) or removed(remove)
  *
  * @apiExample {curl} Example call:
  * curl -X "POST" https://habitica.com/api/v3/tasks/unlink-one/ee882e1d-ebd1-4716-88f2-4f9e47d947a8?keep=keep
@@ -1198,7 +1198,7 @@ api.clearCompletedTodos = {
  * @apiName DeleteTask
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id or alias
+ * @apiParam (Path) {String} taskId The task _id or alias
  *
  * @apiExample {json} Example call:
  * curl -X "DELETE" https://habitica.com/api/v3/tasks/3d5d324d-a042-4d5f-872e-0553e228553e

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

@@ -33,7 +33,7 @@ let api = {};
  * @apiName CreateGroupTasks
  * @apiGroup Task
  *
- * @apiParam {UUID} groupId The id of the group the new task(s) will belong to
+ * @apiParam (Path) {UUID} groupId The id of the group the new task(s) will belong to
  *
  * @apiSuccess data An object if a single task was created, otherwise an array of tasks
  */
@@ -66,8 +66,8 @@ api.createGroupTasks = {
  * @apiName GetGroupTasks
  * @apiGroup Task
  *
- * @apiParam {UUID} groupId The id of the group from which to retrieve the tasks
+ * @apiParam (Path) {UUID} groupId The id of the group from which to retrieve the tasks
- * @apiParam {string="habits","dailys","todos","rewards"} type Optional query parameter to return just a type of tasks
+ * @apiParam (Query) {string="habits","dailys","todos","rewards"} [type] Query parameter to return just a type of tasks
  *
  * @apiSuccess {Array} data An array of tasks
  */
@@ -99,8 +99,8 @@ api.getGroupTasks = {
  * @apiName GroupMoveTask
  * @apiGroup Task
  *
- * @apiParam {String} taskId The task _id
+ * @apiParam (Path) {String} taskId The task _id
- * @apiParam {Number} position Query parameter - Where to move the task (-1 means push to bottom). First position is 0
+ * @apiParam (Path) {Number} position Where to move the task (-1 means push to bottom). First position is 0
  *
  * @apiSuccess {Array} data The new tasks order (group.tasksOrder.{task.type}s)
  */
@@ -150,8 +150,8 @@ api.groupMoveTask = {
  * @apiName AssignTask
  * @apiGroup Task
  *
- * @apiParam {UUID} taskId The id of the task that will be assigned
+ * @apiParam (Path) {UUID} taskId The id of the task that will be assigned
- * @apiParam {UUID} userId The id of the user that will be assigned to the task
+ * @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
  */
@@ -208,8 +208,8 @@ api.assignTask = {
  * @apiName UnassignTask
  * @apiGroup Task
  *
- * @apiParam {UUID} taskId The id of the task that will be assigned
+ * @apiParam (Path) {UUID} taskId The id of the task that will be assigned
- * @apiParam {UUID} userId The id of the user that will be assigned to the 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
  */
@@ -258,8 +258,8 @@ api.unassignTask = {
  * @apiName ApproveTask
  * @apiGroup Task
  *
- * @apiParam {UUID} taskId The id of the task that is the original group task
+ * @apiParam (Path) {UUID} taskId The id of the task that is the original group task
- * @apiParam {UUID} userId The id of the user that will be approved
+ * @apiParam (Path) {UUID} userId The id of the user that will be approved
  *
  * @apiSuccess task The approved task
  */
@@ -339,7 +339,7 @@ api.approveTask = {
  * @apiName GetGroupApprovals
  * @apiGroup Task
  *
- * @apiParam {UUID} groupId The id of the group from which to retrieve the approvals
+ * @apiParam (Path) {UUID} groupId The id of the group from which to retrieve the approvals
  *
  * @apiSuccess {Array} data An array of tasks
  */

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

@@ -344,8 +344,8 @@ api.updateUser = {
  * @apiName UserDelete
  * @apiGroup User
  *
- * @apiParam {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
- * @apiParam {String} feedback User's optional feedback explaining reasons for deletion
+ * @apiParam (Body) {String} feedback User's optional feedback explaining reasons for deletion
  *
  * @apiSuccess {Object} data An empty Object
  *
@@ -515,7 +515,7 @@ const partyMembersFields = 'profile.name stats achievements items.special';
  * @apiGroup User
  *
 
- * @apiParam {String=fireball, mpHeal, earth, frost, smash, defensiveStance, valorousPresence, intimidate, pickPocket, backStab, toolsOfTrade, stealth, heal, protectAura, brightness, healAll} spellId The skill to cast.
+ * @apiParam (Path) {String=fireball, mpHeal, earth, frost, smash, defensiveStance, valorousPresence, intimidate, pickPocket, backStab, toolsOfTrade, stealth, heal, protectAura, brightness, healAll} spellId The skill to cast.
  * @apiParam (Query) {UUID} targetId Query parameter, necessary if the spell is cast on a party member or task. Not used if the spell is case on the user or the user's current party.
  * @apiParamExample {json} Query example:
  * Cast "Pickpocket" on a task:
@@ -834,7 +834,7 @@ api.allocateNow = {
  * @apiName UserBuy
  * @apiGroup User
  *
- * @apiParam {String} key The item to buy
+ * @apiParam (Path) {String} key The item to buy
  *
  * @apiSuccess data User's data profile
  * @apiSuccess message Item purchased
@@ -874,7 +874,7 @@ api.buy = {
  * @apiName UserBuyGear
  * @apiGroup User
  *
- * @apiParam {String} key The item to buy
+ * @apiParam (Path) {String} key The item to buy
  *
  * @apiSuccess {Object} data.items User's item inventory
  * @apiSuccess {Object} data.flags User's flags
@@ -999,7 +999,7 @@ api.buyHealthPotion = {
  * @apiName UserBuyMysterySet
  * @apiGroup User
  *
- * @apiParam {String} key The mystery set to buy
+ * @apiParam (Path) {String} key The mystery set to buy
  *
  * @apiSuccess {Object} data.items user.items
  * @apiSuccess {Object} data.purchasedPlanConsecutive user.purchased.plan.consecutive
@@ -1039,7 +1039,7 @@ api.buyMysterySet = {
  * @apiName UserBuyQuest
  * @apiGroup User
  *
- * @apiParam {String} key The quest scroll to buy
+ * @apiParam (Path) {String} key The quest scroll to buy
  *
  * @apiSuccess {Object} data.quests User's quest list
  * @apiSuccess {String} message Success message
@@ -1080,7 +1080,7 @@ api.buyQuest = {
  * @apiName UserBuySpecialSpell
  * @apiGroup User
  *
- * @apiParam {String} key The special item to buy. Must be one of the keys from "content.special", such as birthday, snowball, salt.
+ * @apiParam (Path) {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's current stats
  * @apiSuccess {Object} data.items User's current inventory
@@ -1118,8 +1118,8 @@ api.buySpecialSpell = {
  * @apiName UserHatch
  * @apiGroup User
  *
- * @apiParam {String} egg The egg to use
+ * @apiParam (Path) {String} egg The egg to use
- * @apiParam {String} hatchingPotion The hatching potion to use
+ * @apiParam (Path) {String} hatchingPotion The hatching potion to use
  * @apiParamExample {URL} Example-URL
  * https://habitica.com/api/v3/user/hatch/Dragon/CottonCandyPink
  *
@@ -1161,8 +1161,8 @@ api.hatch = {
  * @apiName UserEquip
  * @apiGroup User
  *
- * @apiParam {String="mount","pet","costume","equipped"} type The type of item to equip
+ * @apiParam (Path) {String="mount","pet","costume","equipped"} type The type of item to equip
- * @apiParam {String} key The item to equip
+ * @apiParam (Path) {String} key The item to equip
  *
  * @apiParamExample {URL} Example-URL
  * https://habitica.com/api/v3/user/equip/equipped/weapon_warrior_2
@@ -1202,8 +1202,8 @@ api.equip = {
  * @apiName UserFeed
  * @apiGroup User
  *
- * @apiParam {String} pet
+ * @apiParam (Path) {String} pet
- * @apiParam {String} food
+ * @apiParam (Path) {String} food
  *
  * @apiParamExample {url} Example-URL
  * https://habitica.com/api/v3/user/feed/Armadillo-Shade/Chocolate
@@ -1238,7 +1238,7 @@ api.feed = {
  * @apiName UserChangeClass
  * @apiGroup User
  *
- * @apiParam {String} class Query parameter - ?class={warrior|rogue|wizard|healer}
+ * @apiParam (Query) {String} class Query parameter - ?class={warrior|rogue|wizard|healer}
  *
  * @apiSuccess {Object} data.flags user.flags
  * @apiSuccess {Object} data.stats user.stats
@@ -1289,8 +1289,8 @@ api.disableClasses = {
  * @apiName UserPurchase
  * @apiGroup User
  *
- * @apiParam {String="gems","eggs","hatchingPotions","premiumHatchingPotions",food","quests","gear"} type Type of item to purchase.
+ * @apiParam (Path) {String="gems","eggs","hatchingPotions","premiumHatchingPotions",food","quests","gear"} type Type of item to purchase.
- * @apiParam {String} key Item's key (use "gem" for purchasing gems)
+ * @apiParam (Path) {String} key Item's key (use "gem" for purchasing gems)
  *
  * @apiSuccess {Object} data.items user.items
  * @apiSuccess {Number} data.balance user.balance
@@ -1332,8 +1332,8 @@ api.purchase = {
  * @apiName UserPurchaseHourglass
  * @apiGroup User
  *
- * @apiParam {String="pets","mounts"} type The type of item to purchase
+ * @apiParam (Path) {String="pets","mounts"} type The type of item to purchase
- * @apiParam {String} key Ex: {Phoenix-Base}. The key for the mount/pet
+ * @apiParam (Path) {String} key Ex: {Phoenix-Base}. The key for the mount/pet
  *
  * @apiSuccess {Object} data.items user.items
  * @apiSuccess {Object} data.purchasedPlanConsecutive user.purchased.plan.consecutive
@@ -1363,7 +1363,7 @@ api.userPurchaseHourglass = {
  * @apiName UserReadCard
  * @apiGroup User
  *
- * @apiParam {String} cardType Type of card to read (e.g. - birthday, greeting, nye, thankyou, valentine)
+ * @apiParam (Path) {String} cardType Type of card to read (e.g. - birthday, greeting, nye, thankyou, valentine)
  *
  * @apiSuccess {Object} data.specialItems user.items.special
  * @apiSuccess {Boolean} data.cardReceived user.flags.cardReceived
@@ -1570,7 +1570,7 @@ api.userReleaseMounts = {
 };
 
 /**
- * @api {post} /api/v3/user/sell/:type/:key?amount=1 Sell a gold-sellable item owned by the user
+ * @api {post} /api/v3/user/sell/:type/:key Sell a gold-sellable item owned by the user
  * @apiName UserSell
  * @apiGroup User
  *
@@ -1604,7 +1604,7 @@ api.userSell = {
  * @apiName UserUnlock
  * @apiGroup User
  *
- * @apiParam {String} path Query parameter. Full path to unlock. See "content" API call for list of items.
+ * @apiParam (Query) {String} path Full path to unlock. See "content" API call for list of items.
  *
  * @apiParamExample {curl}
  * curl -x POST http://habitica.com/api/v3/user/unlock?path=background.midnight_clouds
@@ -1738,7 +1738,7 @@ api.userRebirth = {
  * @apiName BlockUser
  * @apiGroup User
  *
- * @apiParam {UUID} uuid The uuid of the user to block / unblock
+ * @apiParam (Path) {UUID} uuid The uuid of the user to block / unblock
  *
  * @apiSuccess {Array} data user.inbox.blocks
  *
@@ -1765,7 +1765,7 @@ api.blockUser = {
  * @apiName deleteMessage
  * @apiGroup User
  *
- * @apiParam {UUID} id The id of the message to delete
+ * @apiParam (Path) {UUID} id The id of the message to delete
  *
  * @apiSuccess {Object} data user.inbox.messages
  * @apiSuccessExample {json}