Explain some of the dynamics with comments

packages/block-editor/src/components/block-list/block-contextual-toolbar.js

@@ -39,6 +39,7 @@ function BlockContextualToolbar( { focusOnMount, ...props } ) {
 		}
 	}
 
+	// Shifts the toolbar to make room for the parent block selector.
 	const classes = classnames( 'block-editor-block-contextual-toolbar', {
 		'with-offset': hasParents,
 	} );

packages/block-editor/src/components/block-parent-selector/index.js

@@ -54,6 +54,8 @@ export default function BlockParentSelector() {
 		};
 	}, [] );
 
+	// Allows highlighting the parent block outline when focusing or hovering
+	// the parent block selector within the child.
 	const nodeRef = useRef();
 	const { gestures: showMoversGestures } = useShowMoversGestures( {
 		ref: nodeRef,

packages/block-editor/src/components/block-toolbar/index.js

@@ -64,9 +64,10 @@ export default function BlockToolbar( { hideDragHandle } ) {
 		};
 	}, [] );
 
+	// Handles highlighting the current block outline on hover or focus of the
+	// block type toolbar area.
 	const { toggleBlockHighlight } = useDispatch( 'core/block-editor' );
 	const nodeRef = useRef();
-
 	const { showMovers, gestures: showMoversGestures } = useShowMoversGestures(
 		{
 			ref: nodeRef,
@@ -79,6 +80,8 @@ export default function BlockToolbar( { hideDragHandle } ) {
 		}
 	);
 
+	// Account for the cases where the block toolbar is rendered within the
+	// header are and not contextually to the block.
 	const displayHeaderToolbar =
 		useViewportMatch( 'medium', '<' ) || hasFixedToolbar;