Merge pull request #9558 from Expensify/marco-jsdoc-API.js

[No QA] update JSDoc for API.js functions

src/libs/API.js

@@ -4,6 +4,19 @@ import * as Request from './Request';
 import * as SequentialQueue from './Network/SequentialQueue';
 import {version} from '../../package.json';
 
+/**
+ * All calls to API.write() will be persisted to disk as JSON with the params, successData, and failureData.
+ * This is so that if the network is unavailable or the app is closed, we can send the WRITE request later.
+ *
+ * @param {String} command - Name of API command to call.
+ * @param {Object} apiCommandParameters - Parameters to send to the API.
+ * @param {Object} onyxData  - Object containing errors, loading states, and optimistic UI data that will be merged
+ *                             into Onyx before and after a request is made. Each nested object will be formatted in
+ *                             the same way as an API response.
+ * @param {Object} [onyxData.optimisticData] - Onyx instructions that will be passed to Onyx.update() before the request is made.
+ * @param {Object} [onyxData.successData] - Onyx instructions that will be passed to Onyx.update() when the response has jsonCode === 200.
+ * @param {Object} [onyxData.failureData] - Onyx instructions that will be passed to Onyx.update() when the response has jsonCode !== 200.
+ */
 function write(command, apiCommandParameters = {}, onyxData = {}) {
     // Optimistically update Onyx
     if (onyxData.optimisticData) {
@@ -33,6 +46,24 @@ function write(command, apiCommandParameters = {}, onyxData = {}) {
     SequentialQueue.push(request);
 }
 
+/**
+ * For commands where the network response must be accessed directly or when there is functionality that can only
+ * happen once the request is finished (eg. calling third-party services like Onfido and Plaid, redirecting a user
+ * depending on the response data, etc.).
+ * It works just like API.read(), except that it will return a promise.
+ * Using this method is discouraged and will throw an ESLint error. Use it sparingly and only when all other alternatives have been exhausted.
+ * It is best to discuss it in Slack anytime you are tempted to use this method.
+ *
+ * @param {String} command - Name of API command to call.
+ * @param {Object} apiCommandParameters - Parameters to send to the API.
+ * @param {Object} onyxData  - Object containing errors, loading states, and optimistic UI data that will be merged
+ *                             into Onyx before and after a request is made. Each nested object will be formatted in
+ *                             the same way as an API response.
+ * @param {Object} [onyxData.optimisticData] - Onyx instructions that will be passed to Onyx.update() before the request is made.
+ * @param {Object} [onyxData.successData] - Onyx instructions that will be passed to Onyx.update() when the response has jsonCode === 200.
+ * @param {Object} [onyxData.failureData] - Onyx instructions that will be passed to Onyx.update() when the response has jsonCode !== 200.
+ * @returns {Promise}
+ */
 function makeRequestWithSideEffects(command, apiCommandParameters = {}, onyxData = {}) {
     // Optimistically update Onyx
     if (onyxData.optimisticData) {
@@ -56,6 +87,18 @@ function makeRequestWithSideEffects(command, apiCommandParameters = {}, onyxData
     return Request.processWithMiddleware(request);
 }
 
+/**
+ * Requests made with this method are not be persisted to disk. If there is no network connectivity, the request is ignored and discarded.
+ *
+ * @param {String} command - Name of API command to call.
+ * @param {Object} apiCommandParameters - Parameters to send to the API.
+ * @param {Object} onyxData  - Object containing errors, loading states, and optimistic UI data that will be merged
+ *                             into Onyx before and after a request is made. Each nested object will be formatted in
+ *                             the same way as an API response.
+ * @param {Object} [onyxData.optimisticData] - Onyx instructions that will be passed to Onyx.update() before the request is made.
+ * @param {Object} [onyxData.successData] - Onyx instructions that will be passed to Onyx.update() when the response has jsonCode === 200.
+ * @param {Object} [onyxData.failureData] - Onyx instructions that will be passed to Onyx.update() when the response has jsonCode !== 200.
+ */
 function read(command, apiCommandParameters, onyxData) {
     makeRequestWithSideEffects(command, apiCommandParameters, onyxData);
 }