From 7810f7bdc29f3ba798aee28e5c70c97d8825fda0 Mon Sep 17 00:00:00 2001
From: Aurooba Ahmed <hey@aurooba.com>
Date: Sun, 9 Apr 2023 01:39:32 -0600
Subject: [PATCH] Update documentation for setGroupingBlockName (#49670)

* Update documentation for setGroupingBlockName

* Add explainer text for setGroupingBlockName

Add extra explainer text on what setGroupingBlockName does and that it needs to be executed once the DOM is fully loaded.

* generate updated docs
---
 packages/blocks/README.md               | 6 +++++-
 packages/blocks/src/api/registration.js | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/packages/blocks/README.md b/packages/blocks/README.md
index a7c7ba9e0d6beb..aec255ce79fee4 100644
--- a/packages/blocks/README.md
+++ b/packages/blocks/README.md
@@ -911,6 +911,10 @@ _Parameters_
 
 Assigns name of block for handling block grouping interactions.
 
+This function lets you select a different block to group other blocks in instead of the
+default `core/group` block. This function must be used in a component or when the DOM is fully
+loaded. See <https://developer.wordpress.org/block-editor/reference-guides/packages/packages-dom-ready/>
+
 _Usage_
 
 ```js
@@ -919,7 +923,7 @@ import { setGroupingBlockName } from '@wordpress/blocks';
 const ExampleComponent = () => {
 	return (
 		<Button onClick={ () => setGroupingBlockName( 'core/columns' ) }>
-			{ __( 'Set the default block to Heading' ) }
+			{ __( 'Wrap in columns' ) }
 		</Button>
 	);
 };
diff --git a/packages/blocks/src/api/registration.js b/packages/blocks/src/api/registration.js
index a2d5a34d79fdf7..2c86850dc42527 100644
--- a/packages/blocks/src/api/registration.js
+++ b/packages/blocks/src/api/registration.js
@@ -523,6 +523,10 @@ export function setDefaultBlockName( name ) {
 /**
  * Assigns name of block for handling block grouping interactions.
  *
+ * This function lets you select a different block to group other blocks in instead of the
+ * default `core/group` block. This function must be used in a component or when the DOM is fully
+ * loaded. See https://developer.wordpress.org/block-editor/reference-guides/packages/packages-dom-ready/
+ *
  * @param {string} name Block name.
  *
  * @example
@@ -533,7 +537,7 @@ export function setDefaultBlockName( name ) {
  *
  *     return (
  *         <Button onClick={ () => setGroupingBlockName( 'core/columns' ) }>
- *             { __( 'Set the default block to Heading' ) }
+ *             { __( 'Wrap in columns' ) }
  *         </Button>
  *     );
  * };