diff --git a/packages/block-directory/README.md b/packages/block-directory/README.md
index 16ef9ac8bc8d30..77b6f9afc551b0 100644
--- a/packages/block-directory/README.md
+++ b/packages/block-directory/README.md
@@ -14,4 +14,244 @@ npm install @wordpress/block-directory --save
_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._
+## Usage
+
+This package builds a standalone JS file. When loaded on a page with the block editor, it extends the block inserter to search for blocks from WordPress.org.
+
+To do this, it uses the `__experimentalInserterMenuExtension`, a slot-fill area hooked into the block types list. When the user runs a search and there are no results currently installed, it fires off a request to WordPress.org for matching blocks. These are listed for the user to install with a one-click process that [installs, activates, and injects the block into the post.](./src/store/actions.js#L49) When the post is saved, if the block was not used, it will be [silently uninstalled](./src/store/actions.js#L129) to avoid clutter.
+
+See also the API endpoints for searching WordPress.org: `/wp/v2/block-directory/search`, and installing & activating plugins: `/wp/v2/plugins/`.
+
+## Actions
+
+The following set of dispatching action creators are available on the object returned by `wp.data.dispatch( 'core/block-directory' )`:
+
+
+
+# **addInstalledBlockType**
+
+Returns an action object used to add a block type to the "newly installed"
+tracking list.
+
+_Parameters_
+
+- _item_ `Object`: The block item with the block id and name.
+
+_Returns_
+
+- `Object`: Action object.
+
+# **clearErrorNotice**
+
+Sets the error notice to empty for specific block.
+
+_Parameters_
+
+- _blockId_ `string`: The ID of the block plugin. eg: my-block
+
+_Returns_
+
+- `Object`: Action object.
+
+# **fetchDownloadableBlocks**
+
+Returns an action object used in signalling that the downloadable blocks
+have been requested and are loading.
+
+_Parameters_
+
+- _filterValue_ `string`: Search string.
+
+_Returns_
+
+- `Object`: Action object.
+
+# **installBlockType**
+
+Action triggered to install a block plugin.
+
+_Parameters_
+
+- _block_ `Object`: The block item returned by search.
+
+_Returns_
+
+- `boolean`: Whether the block was successfully installed & loaded.
+
+# **receiveDownloadableBlocks**
+
+Returns an action object used in signalling that the downloadable blocks
+have been updated.
+
+_Parameters_
+
+- _downloadableBlocks_ `Array`: Downloadable blocks.
+- _filterValue_ `string`: Search string.
+
+_Returns_
+
+- `Object`: Action object.
+
+# **removeInstalledBlockType**
+
+Returns an action object used to remove a block type from the "newly installed"
+tracking list.
+
+_Parameters_
+
+- _item_ `string`: The block item with the block id and name.
+
+_Returns_
+
+- `Object`: Action object.
+
+# **setErrorNotice**
+
+Sets an error notice to be displayed to the user for a given block.
+
+_Parameters_
+
+- _blockId_ `string`: The ID of the block plugin. eg: my-block
+- _message_ `string`: The message shown in the notice.
+- _isFatal_ `boolean`: Whether the user can recover from the error.
+
+_Returns_
+
+- `Object`: Action object.
+
+# **setIsInstalling**
+
+Returns an action object used to indicate install in progress.
+
+_Parameters_
+
+- _blockId_ `string`:
+- _isInstalling_ `boolean`:
+
+_Returns_
+
+- `Object`: Action object.
+
+# **uninstallBlockType**
+
+Action triggered to uninstall a block plugin.
+
+_Parameters_
+
+- _block_ `Object`: The blockType object.
+
+
+
+## Selectors
+
+The following selectors are available on the object returned by `wp.data.select( 'core/block-directory' )`:
+
+
+
+# **getDownloadableBlocks**
+
+Returns the available uninstalled blocks.
+
+_Parameters_
+
+- _state_ `Object`: Global application state.
+- _filterValue_ `string`: Search string.
+
+_Returns_
+
+- `Array`: Downloadable blocks.
+
+# **getErrorNoticeForBlock**
+
+Returns the error notice for a given block.
+
+_Parameters_
+
+- _state_ `Object`: Global application state.
+- _blockId_ `string`: The ID of the block plugin. eg: my-block
+
+_Returns_
+
+- `(string|boolean)`: The error text, or false if no error.
+
+# **getErrorNotices**
+
+Returns all block error notices.
+
+_Parameters_
+
+- _state_ `Object`: Global application state.
+
+_Returns_
+
+- `Object`: Object with error notices.
+
+# **getInstalledBlockTypes**
+
+Returns the block types that have been installed on the server in this
+session.
+
+_Parameters_
+
+- _state_ `Object`: Global application state.
+
+_Returns_
+
+- `Array`: Block type items
+
+# **getNewBlockTypes**
+
+Returns block types that have been installed on the server and used in the
+current post.
+
+_Parameters_
+
+- _state_ `Object`: Global application state.
+
+_Returns_
+
+- `Array`: Block type items.
+
+# **getUnusedBlockTypes**
+
+Returns the block types that have been installed on the server but are not
+used in the current post.
+
+_Parameters_
+
+- _state_ `Object`: Global application state.
+
+_Returns_
+
+- `Array`: Block type items.
+
+# **isInstalling**
+
+Returns true if a block plugin install is in progress.
+
+_Parameters_
+
+- _state_ `Object`: Global application state.
+- _blockId_ `string`: Id of the block.
+
+_Returns_
+
+- `boolean`: Whether this block is currently being installed.
+
+# **isRequestingDownloadableBlocks**
+
+Returns true if application is requesting for downloadable blocks.
+
+_Parameters_
+
+- _state_ `Object`: Global application state.
+- _filterValue_ `string`: Search string.
+
+_Returns_
+
+- `boolean`: Whether a request is in progress for the blocks list.
+
+
+
+
diff --git a/packages/block-directory/src/store/actions.js b/packages/block-directory/src/store/actions.js
index 9f1e96d5db26ba..905c46590a654a 100644
--- a/packages/block-directory/src/store/actions.js
+++ b/packages/block-directory/src/store/actions.js
@@ -12,7 +12,7 @@ import getPluginUrl from './utils/get-plugin-url';
/**
* Returns an action object used in signalling that the downloadable blocks
- * have been requested and is loading.
+ * have been requested and are loading.
*
* @param {string} filterValue Search string.
*
@@ -150,7 +150,8 @@ export function* uninstallBlockType( block ) {
}
/**
- * Returns an action object used to add a newly installed block type.
+ * Returns an action object used to add a block type to the "newly installed"
+ * tracking list.
*
* @param {Object} item The block item with the block id and name.
*
@@ -164,7 +165,8 @@ export function addInstalledBlockType( item ) {
}
/**
- * Returns an action object used to remove a newly installed block type.
+ * Returns an action object used to remove a block type from the "newly installed"
+ * tracking list.
*
* @param {string} item The block item with the block id and name.
*
@@ -178,7 +180,7 @@ export function removeInstalledBlockType( item ) {
}
/**
- * Returns an action object used to indicate install in progress
+ * Returns an action object used to indicate install in progress.
*
* @param {string} blockId
* @param {boolean} isInstalling
@@ -194,11 +196,11 @@ export function setIsInstalling( blockId, isInstalling ) {
}
/**
- * Sets an error notice string to be displayed to the user
+ * Sets an error notice to be displayed to the user for a given block.
*
- * @param {string} blockId The ID of the block plugin. eg: my-block
+ * @param {string} blockId The ID of the block plugin. eg: my-block
* @param {string} message The message shown in the notice.
- * @param {boolean} isFatal Whether the user can recover from the error
+ * @param {boolean} isFatal Whether the user can recover from the error.
*
* @return {Object} Action object.
*/
@@ -212,7 +214,7 @@ export function setErrorNotice( blockId, message, isFatal = false ) {
}
/**
- * Sets the error notice to empty for specific block
+ * Sets the error notice to empty for specific block.
*
* @param {string} blockId The ID of the block plugin. eg: my-block
*
diff --git a/packages/block-directory/src/store/selectors.js b/packages/block-directory/src/store/selectors.js
index 2d14bb029467fd..dbf94678436e82 100644
--- a/packages/block-directory/src/store/selectors.js
+++ b/packages/block-directory/src/store/selectors.js
@@ -11,11 +11,10 @@ import hasBlockType from './utils/has-block-type';
/**
* Returns true if application is requesting for downloadable blocks.
*
- * @param {Object} state Global application state.
+ * @param {Object} state Global application state.
* @param {string} filterValue Search string.
*
- *
- * @return {Array} Downloadable blocks
+ * @return {boolean} Whether a request is in progress for the blocks list.
*/
export function isRequestingDownloadableBlocks( state, filterValue ) {
if (
@@ -28,12 +27,12 @@ export function isRequestingDownloadableBlocks( state, filterValue ) {
}
/**
- * Returns the available uninstalled blocks
+ * Returns the available uninstalled blocks.
*
* @param {Object} state Global application state.
* @param {string} filterValue Search string.
*
- * @return {Array} Downloadable blocks
+ * @return {Array} Downloadable blocks.
*/
export function getDownloadableBlocks( state, filterValue ) {
if (
@@ -46,11 +45,12 @@ export function getDownloadableBlocks( state, filterValue ) {
}
/**
- * Returns the block types that have been installed on the server.
+ * Returns the block types that have been installed on the server in this
+ * session.
*
* @param {Object} state Global application state.
*
- * @return {Array} Block type items.
+ * @return {Array} Block type items
*/
export function getInstalledBlockTypes( state ) {
return state.blockManagement.installedBlockTypes;
@@ -95,19 +95,19 @@ export const getUnusedBlockTypes = createRegistrySelector(
);
/**
- * Returns true if application is calling install endpoint.
+ * Returns true if a block plugin install is in progress.
*
- * @param {Object} state Global application state.
+ * @param {Object} state Global application state.
* @param {string} blockId Id of the block.
*
- * @return {boolean} Whether its currently installing
+ * @return {boolean} Whether this block is currently being installed.
*/
export function isInstalling( state, blockId ) {
return state.blockManagement.isInstalling[ blockId ] || false;
}
/**
- * Returns the error notices
+ * Returns all block error notices.
*
* @param {Object} state Global application state.
*