Add doc comments

packages/block-editor/src/components/block-editing-mode/index.js

@@ -11,6 +11,37 @@ import { store as blockEditorStore } from '../../store';
 import { unlock } from '../../lock-unlock';
 import { BlockListBlockContext } from '../block-list/block';
 
+/**
+ * Allows a block to restrict the user interface that is displayed for editing
+ * that block and its inner blocks.
+ *
+ * @example
+ * ```js
+ * function MyBlock( { attributes, setAttributes } ) {
+ *     useBlockEditingMode( 'disabled' );
+ *     return <div { ...useBlockProps() }></div>;
+ * }
+ * ```
+ *
+ * `mode` can be one of three options:
+ *
+ * - `'disabled'`: Prevents editing the block entirely, i.e. it cannot be
+ *   selected.
+ * - `'contentOnly'`: Hides all non-content UI, e.g. auxiliary controls in the
+ *   toolbar, the block movers, block settings.
+ * - `'default'`: Allows editing the block as normal.
+ *
+ * The mode is inherited by all of the block's inner blocks, unless they have
+ * their own mode.
+ *
+ * If called outside of a block context, the mode is applied to all blocks.
+ *
+ * @param {?string} mode The editing mode to apply. If undefined, the current
+ *                       editing mode is not changed. One of `'disabled'`,
+ *                       `'contentOnly'`, or `'default'`.
+ *
+ * @return {string} The current editing mode.
+ */
 export function useBlockEditingMode( mode ) {
 	const { clientId = '' } = useContext( BlockListBlockContext ) ?? {};
 	const blockEditingMode = useSelect(

packages/block-editor/src/store/private-actions.js

@@ -67,6 +67,17 @@ export function showBlockInterface() {
 	};
 }
 
+/**
+ * Sets the block editing mode for a given block.
+ *
+ * @see useBlockEditingMode
+ *
+ * @param {string} clientId The block client ID, or `''` for the root container.
+ * @param {string} mode     The block editing mode. One of `'disabled'`,
+ *                          `'contentOnly'`, or `'default'`.
+ *
+ * @return {Object} Action object.
+ */
 export function setBlockEditingMode( clientId = '', mode ) {
 	return {
 		type: 'SET_BLOCK_EDITING_MODE',
@@ -75,6 +86,15 @@ export function setBlockEditingMode( clientId = '', mode ) {
 	};
 }
 
+/**
+ * Clears the block editing mode for a given block.
+ *
+ * @see useBlockEditingMode
+ *
+ * @param {string} clientId The block client ID, or `''` for the root container.
+ *
+ * @return {Object} Action object.
+ */
 export function unsetBlockEditingMode( clientId = '' ) {
 	return {
 		type: 'UNSET_BLOCK_EDITING_MODE',

packages/block-editor/src/store/private-selectors.js

@@ -39,31 +39,62 @@ export function getLastInsertedBlocksClientIds( state ) {
 	return state?.lastBlockInserted?.clientIds;
 }
 
+/**
+ * Returns the block editing mode for a given block.
+ *
+ * The mode can be one of three options:
+ *
+ * - `'disabled'`: Prevents editing the block entirely, i.e. it cannot be
+ *   selected.
+ * - `'contentOnly'`: Hides all non-content UI, e.g. auxiliary controls in the
+ *   toolbar, the block movers, block settings.
+ * - `'default'`: Allows editing the block as normal.
+ *
+ * Blocks can set a mode using the `useBlockEditingMode` hook.
+ *
+ * The mode is inherited by all of the block's inner blocks, unless they have
+ * their own mode.
+ *
+ * A template lock can also set a mode. If the template lock is `'contentOnly'`,
+ * the block's mode is overridden to `'contentOnly'` if the block has a content
+ * role attribute, or `'disabled'` otherwise.
+ *
+ * @see useBlockEditingMode
+ *
+ * @param {Object} state    Global application state.
+ * @param {string} clientId The block client ID, or `''` for the root container.
+ *
+ * @return {string} The block editing mode. One of `'disabled'`,
+ *                  `'contentOnly'`, or `'default'`.
+ */
 export const getBlockEditingMode = createRegistrySelector(
-	( select ) => ( state, clientId ) => {
-		const explicitEditingMode = getExplcitBlockEditingMode(
-			state,
-			clientId
-		);
-		const rootClientId = getBlockRootClientId( state, clientId );
-		const templateLock = getTemplateLock( state, rootClientId );
-		const name = getBlockName( state, clientId );
-		const isContent =
-			select( blocksStore ).__experimentalHasContentRoleAttribute( name );
-		if (
-			explicitEditingMode === 'disabled' ||
-			( templateLock === 'contentOnly' && ! isContent )
-		) {
-			return 'disabled';
-		}
-		if (
-			explicitEditingMode === 'contentOnly' ||
-			( templateLock === 'contentOnly' && isContent )
-		) {
-			return 'contentOnly';
+	( select ) =>
+		( state, clientId = '' ) => {
+			const explicitEditingMode = getExplcitBlockEditingMode(
+				state,
+				clientId
+			);
+			const rootClientId = getBlockRootClientId( state, clientId );
+			const templateLock = getTemplateLock( state, rootClientId );
+			const name = getBlockName( state, clientId );
+			const isContent =
+				select( blocksStore ).__experimentalHasContentRoleAttribute(
+					name
+				);
+			if (
+				explicitEditingMode === 'disabled' ||
+				( templateLock === 'contentOnly' && ! isContent )
+			) {
+				return 'disabled';
+			}
+			if (
+				explicitEditingMode === 'contentOnly' ||
+				( templateLock === 'contentOnly' && isContent )
+			) {
+				return 'contentOnly';
+			}
+			return 'default';
 		}
-		return 'default';
-	}
 );
 
 const getExplcitBlockEditingMode = createSelector(

packages/block-editor/src/store/reducer.js

@@ -1834,6 +1834,14 @@ export function temporarilyEditingAsBlocks( state = '', action ) {
 	return state;
 }
 
+/**
+ * Reducer returning a map of block client IDs to block editing modes.
+ *
+ * @param {Map}    state  Current state.
+ * @param {Object} action Dispatched action.
+ *
+ * @return {Map} Updated state.
+ */
 export function blockEditingModes( state = new Map(), action ) {
 	switch ( action.type ) {
 		case 'SET_BLOCK_EDITING_MODE':