From 2c921609c10b30eb8fbbf8e3f0a0baa79113f855 Mon Sep 17 00:00:00 2001
From: Alys <Alys@users.noreply.github.com>
Date: Sun, 12 Aug 2018 20:11:01 +1000
Subject: [PATCH] improve apidocs related to allocating Stat Points and
 user/unlock - fixes #10557 (#10592)

* correct curl parameter (-X for request method; -x for proxy information)

* fix typo in error message

* fix mistakes in apidocs for allocating Stat Points
---
 website/common/errors/commonErrorMessages.js  |  2 +-
 website/server/controllers/api-v3/user.js     |  4 +-
 .../server/controllers/api-v3/user/stats.js   | 37 ++++++++++---------
 3 files changed, 22 insertions(+), 21 deletions(-)

diff --git a/website/common/errors/commonErrorMessages.js b/website/common/errors/commonErrorMessages.js
index dc754b6e366..00a2d38feaf 100644
--- a/website/common/errors/commonErrorMessages.js
+++ b/website/common/errors/commonErrorMessages.js
@@ -2,7 +2,7 @@
 module.exports = {
   invalidAttribute: '"<%= attr %>" is not a valid Stat.',
 
-  statsObjectRequired: '"stats" update is required',
+  statsObjectRequired: '"stats" object is required',
 
   missingTypeParam: '"req.params.type" is required.',
   missingKeyParam: '"req.params.key" is required.',
diff --git a/website/server/controllers/api-v3/user.js b/website/server/controllers/api-v3/user.js
index 83b27e7279d..763caeab2e5 100644
--- a/website/server/controllers/api-v3/user.js
+++ b/website/server/controllers/api-v3/user.js
@@ -1445,8 +1445,8 @@ api.userSell = {
  * @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
- * curl -x POST http://habitica.com/api/v3/user/unlock?path=hair.color.midnight
+ * 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
  *
  * @apiSuccess {Object} data.purchased
  * @apiSuccess {Object} data.items
diff --git a/website/server/controllers/api-v3/user/stats.js b/website/server/controllers/api-v3/user/stats.js
index be303dcb481..658a3e4fbd8 100644
--- a/website/server/controllers/api-v3/user/stats.js
+++ b/website/server/controllers/api-v3/user/stats.js
@@ -5,24 +5,24 @@ import { authWithHeaders } from '../../../middlewares/auth';
 let api = {};
 
 /**
- * @api {post} /api/v3/user/allocate Allocate a single attribute point
+ * @api {post} /api/v3/user/allocate Allocate a single Stat Point (previously called Attribute Point)
  * @apiName UserAllocate
  * @apiGroup User
  *
- * @apiParam (Body) {String="str","con","int","per"} stat Query parameter - Default ='str'
+ * @apiParam (Query) {String="str","con","int","per"} stat The Stat to increase. Default is 'str'
  *
- * @apiParamExample {json} Example request
- * {"stat":"int"}
+ * @apiParamExample {curl}
+ * curl -X POST -d "" https://habitica.com/api/v3/user/allocate?stat=int
  *
- * @apiSuccess {Object} data Returns stats from the user profile
+ * @apiSuccess {Object} data Returns stats and notifications from the user profile
  *
- * @apiError {NotAuthorized} NoPoints Not enough attribute points to increment a stat.
+ * @apiError {NotAuthorized} NoPoints You don't have enough Stat Points.
  *
  * @apiErrorExample {json}
  *  {
  *   "success": false,
  *   "error": "NotAuthorized",
- *   "message": "You don't have enough attribute points."
+ *   "message": "You don't have enough Stat Points."
  * }
  */
 api.allocate = {
@@ -40,7 +40,7 @@ api.allocate = {
 };
 
 /**
- * @api {post} /api/v3/user/allocate-bulk Allocate multiple attribute points
+ * @api {post} /api/v3/user/allocate-bulk Allocate multiple Stat Points
  * @apiName UserAllocateBulk
  * @apiGroup User
  *
@@ -49,22 +49,22 @@ api.allocate = {
  * @apiParamExample {json} Example request
  * {
  *  stats: {
- *    'int': int,
- *    'str': int,
- *    'con': int,
- *    'per': int,
- *  },
+ *    "int": int,
+ *    "str": str,
+ *    "con": con,
+ *    "per": per
+ *  }
  * }
  *
- * @apiSuccess {Object} data Returns stats from the user profile
+ * @apiSuccess {Object} data Returns stats and notifications from the user profile
  *
- * @apiError {NotAuthorized} NoPoints Not enough attribute points to increment a stat.
+ * @apiError {NotAuthorized} NoPoints You don't have enough Stat Points.
  *
  * @apiErrorExample {json}
  *  {
  *   "success": false,
  *   "error": "NotAuthorized",
- *   "message": "You don't have enough attribute points."
+ *   "message": "You don't have enough Stat Points."
  * }
  */
 api.allocateBulk = {
@@ -82,7 +82,7 @@ api.allocateBulk = {
 };
 
 /**
- * @api {post} /api/v3/user/allocate-now Allocate all attribute points
+ * @api {post} /api/v3/user/allocate-now Allocate all Stat Points
  * @apiDescription Uses the user's chosen automatic allocation method, or if none, assigns all to STR. Note: will return success, even if there are 0 points to allocate.
  * @apiName UserAllocateNow
  * @apiGroup User
@@ -119,7 +119,8 @@ api.allocateBulk = {
  *       "per": 0,
  *       "str": 0,
  *       "con": 0
- *     }
+ *     },
+ *     "notifications": [ .... ],
  *   }
  * }
  *