Tooling: Improve docs build to consider memoized selectors (#9756)

Author: aduth

docs/data/data-core-blocks.md

@@ -2,6 +2,14 @@
 
 ## Selectors
 
+### getBlockTypes
+
+Returns all the available block types.
+
+*Parameters*
+
+ * state: Data state.
+
 ### getBlockType
 
 Returns a block type by name.
@@ -11,6 +19,10 @@ Returns a block type by name.
  * state: Data state.
  * name: Block type name.
 
+*Returns*
+
+Block Type.
+
 ### getCategories
 
 Returns all the available categories.
@@ -47,6 +59,32 @@ Returns the name of the fallback block name.
 
 Fallback block name.
 
+### getChildBlockNames
+
+Returns an array with the child blocks of a given block.
+
+*Parameters*
+
+ * state: Data state.
+ * blockName: Block type name.
+
+*Returns*
+
+Array of child block names.
+
+### hasChildBlocks
+
+Returns a boolean indicating if a block has child blocks or not.
+
+*Parameters*
+
+ * state: Data state.
+ * blockName: Block type name.
+
+*Returns*
+
+True if a block contains child blocks and false otherwise.
+
 ## Actions
 
 ### addBlockTypes

docs/data/data-core-edit-post.md

@@ -167,6 +167,18 @@ Returns the state of legacy meta boxes.
 
 State of meta box at specified location.
 
+### hasMetaBoxes
+
+Returns true if the post is using Meta Boxes
+
+*Parameters*
+
+ * state: Global application state
+
+*Returns*
+
+Whether there are metaboxes or not.
+
 ### isSavingMetaBoxes
 
 Returns true if the Meta Boxes are being saved.

docs/data/data-core-editor.md

@@ -320,6 +320,25 @@ unsaved status values.
 
 Whether the post has been published.
 
+### getBlockDependantsCacheBust
+
+Returns a new reference when the inner blocks of a given block client ID
+change. This is used exclusively as a memoized selector dependant, relying
+on this selector's shared return value and recursively those of its inner
+blocks defined as dependencies. This abuses mechanics of the selector
+memoization to return from the original selector function only when
+dependants change.
+
+*Parameters*
+
+ * state: Editor state.
+ * clientId: Block client ID.
+
+*Returns*
+
+A value whose reference will change only when inner blocks of
+            the given block client ID change.
+
 ### getBlockName
 
 Returns a block's name given its client ID, or null if no block exists with
@@ -334,6 +353,80 @@ the client ID.
 
 Block name.
 
+### getBlock
+
+Returns a block given its client ID. This is a parsed copy of the block,
+containing its `blockName`, `clientId`, and current `attributes` state. This
+is not the block's registration settings, which must be retrieved from the
+blocks module registration store.
+
+*Parameters*
+
+ * state: Editor state.
+ * clientId: Block client ID.
+
+*Returns*
+
+Parsed block object.
+
+### getBlocks
+
+Returns all block objects for the current post being edited as an array in
+the order they appear in the post.
+
+Note: It's important to memoize this selector to avoid return a new instance
+on each call
+
+*Parameters*
+
+ * state: Editor state.
+ * rootClientId: Optional root client ID of block list.
+
+*Returns*
+
+Post blocks.
+
+### getClientIdsWithDescendants
+
+Returns an array containing the clientIds of the top-level blocks
+and their descendants of any depth (for nested blocks).
+
+*Parameters*
+
+ * state: Global application state.
+
+*Returns*
+
+ids of top-level and descendant blocks.
+
+### getGlobalBlockCount
+
+Returns the total number of blocks, or the total number of blocks with a specific name in a post.
+The number returned includes nested blocks.
+
+*Parameters*
+
+ * state: Global application state.
+ * blockName: Optional block name, if specified only blocks of that type will be counted.
+
+*Returns*
+
+Number of blocks in the post, or number of blocks with name equal to blockName.
+
+### getBlocksByClientId
+
+Given an array of block client IDs, returns the corresponding array of block
+objects.
+
+*Parameters*
+
+ * state: Editor state.
+ * clientIds: Client IDs for which blocks are to be returned.
+
+*Returns*
+
+Block objects.
+
 ### getBlockCount
 
 Returns the number of blocks currently present in the post.
@@ -503,6 +596,32 @@ This position is to used to position the caret properly when the selected block
 
 Selected block.
 
+### getMultiSelectedBlockClientIds
+
+Returns the current multi-selection set of block client IDs, or an empty
+array if there is no multi-selection.
+
+*Parameters*
+
+ * state: Editor state.
+
+*Returns*
+
+Multi-selected block client IDs.
+
+### getMultiSelectedBlocks
+
+Returns the current multi-selection set of blocks, or an empty array if
+there is no multi-selection.
+
+*Parameters*
+
+ * state: Editor state.
+
+*Returns*
+
+Multi-selected block objects.
+
 ### getFirstMultiSelectedBlockClientId
 
 Returns the client ID of the first block in the multi-selection set, or null
@@ -558,6 +677,21 @@ false otherwise.
 
 Whether block is in multi-selection set.
 
+### isAncestorMultiSelected
+
+Returns true if an ancestor of the block is multi-selected, or false
+otherwise.
+
+*Parameters*
+
+ * state: Editor state.
+ * clientId: Block client ID.
+
+*Returns*
+
+Whether an ancestor of the block is in multi-selection
+                  set.
+
 ### getMultiSelectedBlocksStartClientId
 
 Returns the client ID of the block which begins the multi-selection set, or
@@ -855,6 +989,19 @@ default post format. Returns null if the format cannot be determined.
 
 Suggested post format.
 
+### getEditedPostContent
+
+Returns the content of the post being edited, preferring raw string edit
+before falling back to serialization of block state.
+
+*Parameters*
+
+ * state: Global application state.
+
+*Returns*
+
+Post content.
+
 ### getNotices
 
 Returns the user notices array.
@@ -867,6 +1014,67 @@ Returns the user notices array.
 
 List of notices.
 
+### canInsertBlockType
+
+Determines if the given block type is allowed to be inserted, and, if
+parentClientId is provided, whether it is allowed to be nested within the
+given parent.
+
+*Parameters*
+
+ * state: Editor state.
+ * blockName: The name of the given block type, e.g.
+                                'core/paragraph'.
+ * parentClientId: The parent that the given block is to be
+                                nested within, or null.
+
+*Returns*
+
+Whether the given block type is allowed to be inserted.
+
+### getInserterItems
+
+Determines the items that appear in the inserter. Includes both static
+items (e.g. a regular block type) and dynamic items (e.g. a reusable block).
+
+Each item object contains what's necessary to display a button in the
+inserter and handle its selection.
+
+The 'utility' property indicates how useful we think an item will be to the
+user. There are 4 levels of utility:
+
+1. Blocks that are contextually useful (utility = 3)
+2. Blocks that have been previously inserted (utility = 2)
+3. Blocks that are in the common category (utility = 1)
+4. All other blocks (utility = 0)
+
+The 'frecency' property is a heuristic (https://en.wikipedia.org/wiki/Frecency)
+that combines block usage frequenty and recency.
+
+Items are returned ordered descendingly by their 'utility' and 'frecency'.
+
+*Parameters*
+
+ * state: Editor state.
+ * parentClientId: The block we are inserting into, if any.
+
+*Returns*
+
+Items that appear in inserter.
+
+### getReusableBlock
+
+Returns the reusable block with the given ID.
+
+*Parameters*
+
+ * state: Global application state.
+ * ref: The reusable block's ID.
+
+*Returns*
+
+The reusable block, or null if none exists.
+
 ### isSavingReusableBlock
 
 Returns whether or not the reusable block with the given ID is being saved.
@@ -1411,4 +1619,4 @@ Returns an action object used in signalling that the editor settings have been u
 
 *Parameters*
 
- * settings: Updated settings
+ * settings: Updated settings

docs/data/data-core-nux.md

@@ -2,6 +2,16 @@
 
 ## Selectors
 
+### getAssociatedGuide
+
+Returns an object describing the guide, if any, that the given tip is a part
+of.
+
+*Parameters*
+
+ * state: Global application state.
+ * tipId: The tip to query.
+
 ### isTipVisible
 
 Determines whether or not the given tip is showing. Tips are hidden if they
@@ -13,6 +23,10 @@ guide that they have been added to.
  * state: Global application state.
  * tipId: The tip to query.
 
+*Returns*
+
+Whether or not the given tip is showing.
+
 ### areTipsEnabled
 
 Returns whether or not tips are globally enabled.

docs/data/data-core.md

@@ -24,6 +24,19 @@ Returns all available authors.
 
 Authors list.
 
+### getUserQueryResults
+
+Returns all the users returned by a query ID.
+
+*Parameters*
+
+ * state: Data state.
+ * queryID: Query ID.
+
+*Returns*
+
+Users list.
+
 ### getEntitiesByKind
 
 Returns whether the entities for the give kind are loaded.