Add core-data JSDoc

WordPress · Jan 19, 2021 · 0a96262 · 0a96262
1 parent fffb043
commit 0a96262
Show file tree

Hide file tree

Showing 3 changed files with 46 additions and 18 deletions.
diff --git a/docs/designers-developers/developers/data/data-core.md b/docs/designers-developers/developers/data/data-core.md
@@ -531,8 +531,8 @@ _Parameters_
 -   _name_ `string`: Name of the deleted entity.
 -   _recordId_ `string`: Record ID of the deleted entity.
 -   _query_ `?Object`: Special query parameters for the DELETE API call.
--   _options_ (unknown type): 
--   _options.\_\_unstableFetch_ (unknown type): 
+-   _options_ `[Object]`: Delete options.
+-   _options.\_\_unstableFetch_ `[Function]`: Internal use only. Function to call instead of `apiFetch()`. Must return a control descriptor.
 
 <a name="editEntityRecord" href="#editEntityRecord">#</a> **editEntityRecord**
 
@@ -699,7 +699,7 @@ _Parameters_
 -   _record_ `Object`: Record to be saved.
 -   _options_ `Object`: Saving options.
 -   _options.isAutosave_ `[boolean]`: Whether this is an autosave.
--   _options.\_\_unstableFetch_ (unknown type): 
+-   _options.\_\_unstableFetch_ `[Function]`: Internal use only. Function to call instead of `apiFetch()`. Must return a control descriptor.
 
 <a name="undo" href="#undo">#</a> **undo**
 

diff --git a/packages/core-data/README.md b/packages/core-data/README.md
@@ -64,8 +64,8 @@ _Parameters_
 -   _name_ `string`: Name of the deleted entity.
 -   _recordId_ `string`: Record ID of the deleted entity.
 -   _query_ `?Object`: Special query parameters for the DELETE API call.
--   _options_ (unknown type): 
--   _options.\_\_unstableFetch_ (unknown type): 
+-   _options_ `[Object]`: Delete options.
+-   _options.\_\_unstableFetch_ `[Function]`: Internal use only. Function to call instead of `apiFetch()`. Must return a control descriptor.
 
 <a name="editEntityRecord" href="#editEntityRecord">#</a> **editEntityRecord**
 
@@ -232,7 +232,7 @@ _Parameters_
 -   _record_ `Object`: Record to be saved.
 -   _options_ `Object`: Saving options.
 -   _options.isAutosave_ `[boolean]`: Whether this is an autosave.
--   _options.\_\_unstableFetch_ (unknown type): 
+-   _options.\_\_unstableFetch_ `[Function]`: Internal use only. Function to call instead of `apiFetch()`. Must return a control descriptor.
 
 <a name="undo" href="#undo">#</a> **undo**
 

diff --git a/packages/core-data/src/actions.js b/packages/core-data/src/actions.js
@@ -156,12 +156,15 @@ export function receiveEmbedPreview( url, preview ) {
 /**
  * Action triggered to delete an entity record.
  *
- * @param {string} kind              Kind of the deleted entity.
- * @param {string} name              Name of the deleted entity.
- * @param {string} recordId          Record ID of the deleted entity.
- * @param {?Object} query             Special query parameters for the DELETE API call.
- * @param options
- * @param options.__unstableFetch
+ * @param {string}   kind                      Kind of the deleted entity.
+ * @param {string}   name                      Name of the deleted entity.
+ * @param {string}   recordId                  Record ID of the deleted entity.
+ * @param {?Object}  query                     Special query parameters for the
+ *                                             DELETE API call.
+ * @param {Object}   [options]                 Delete options.
+ * @param {Function} [options.__unstableFetch] Internal use only. Function to
+ *                                             call instead of `apiFetch()`.
+ *                                             Must return a control descriptor.
  */
 export function* deleteEntityRecord(
 	kind,
@@ -346,12 +349,15 @@ export function __unstableCreateUndoLevel() {
 /**
  * Action triggered to save an entity record.
  *
- * @param {string} kind                       Kind of the received entity.
- * @param {string} name                       Name of the received entity.
- * @param {Object} record                     Record to be saved.
- * @param {Object} options                    Saving options.
- * @param {boolean} [options.isAutosave=false] Whether this is an autosave.
- * @param options.__unstableFetch
+ * @param {string}   kind                       Kind of the received entity.
+ * @param {string}   name                       Name of the received entity.
+ * @param {Object}   record                     Record to be saved.
+ * @param {Object}   options                    Saving options.
+ * @param {boolean}  [options.isAutosave=false] Whether this is an autosave.
+ * @param {Function} [options.__unstableFetch]  Internal use only. Function to
+ *                                              call instead of `apiFetch()`.
+ *                                              Must return a control
+ *                                              descriptor.
  */
 export function* saveEntityRecord(
 	kind,
@@ -574,6 +580,28 @@ export function* saveEntityRecord(
 	}
 }
 
+/**
+ * Runs multiple core-data actions at the same time using one API request.
+ *
+ * Example:
+ *
+ * ```
+ * const [ savedRecord, updatedRecord, deletedRecord ] =
+ *   await dispatch( 'core' ).__experimentalBatch( [
+ *     ( { saveEntityRecord } ) => saveEntityRecord( 'root', 'widget', widget ),
+ *     ( { saveEditedEntityRecord } ) => saveEntityRecord( 'root', 'widget', 123 ),
+ *     ( { deleteEntityRecord } ) => deleteEntityRecord( 'root', 'widget', 123, null ),
+ *   ] );
+ * ```
+ *
+ * @param {Array} requests Array of functions which are invoked simultaneously.
+ *                         Each function is passed an object containing
+ *                         `saveEntityRecord`, `saveEditedEntityRecord`, and
+ *                         `deleteEntityRecord`.
+ *
+ * @return {Promise} A promise that resolves to an array containing the return
+ *                   values of each function given in `requests`.
+ */
 export function* __experimentalBatch( requests ) {
 	const batch = createBatch();
 	const dispatch = yield getDispatch();