Docs: Further Improve documentation for wp_should_load_separate_core_block_assets().

aaronjorbin · aaronjorbin · commit 3c1ab395ddf4 · 2021-06-29T18:44:45.000Z
In [51256], the documentation was improved, this further improves it. As scripts are not yet a part of what this function does, they are not mentioned explicitly. Assets is used so that the docs don't need a lot of improvements when scripts do come into play.. Props desrosj, SergeyBiryukov, Jorbin. See #53505. git-svn-id: https://develop.svn.wordpress.org/trunk@51263 602fd350-edb4-49c9-b593-d223f7449a82
diff --git a/src/wp-includes/script-loader.php b/src/wp-includes/script-loader.php
@@ -2326,16 +2326,16 @@ function wp_should_load_block_editor_scripts_and_styles() {
 }
 
 /**
- * Checks whether separate assets should be loaded for core blocks on-render.
+ * Checks whether separate styles should be loaded for core blocks on-render.
  *
  * When this function returns true, other functions ensure that core blocks
- * only load their styles on-render, and each block loads its own, individual
- * stylesheet. Third-party blocks only load their styles when rendered.
+ * only load their assets on-render, and each block loads its own, individual
+ * assets. Third-party blocks only load their assets when rendered.
  *
- * When this function returns false, all core block styles are loaded regardless
+ * When this function returns false, all core block assets are loaded regardless
  * of whether they are rendered in a page or not, because they are all part of
- * the `block-library/style.css` file. Third-party blocks always get enqueued
- * regardless of whether they are rendered or not.
+ * the `block-library/style.css` file. Assets for third-party blocks are always
+ * enqueued regardless of whether they are rendered or not.
  *
  * This only affects front end and not the block editor screens.
  *
@@ -2352,13 +2352,15 @@ function wp_should_load_separate_core_block_assets() {
 	}
 
 	/**
-	 * Filters the flag that decides whether separate scripts and styles
-	 * will be loaded for core blocks on-render.
+	 * Filters whether block styles should be loaded separately.
+	 *
+	 * Returning false loads all core block assets, regardless of whether they are rendered
+	 * in a page or not. Returning true loads core block assets only when they are rendered.
 	 *
 	 * @since 5.8.0
 	 *
 	 * @param bool $load_separate_assets Whether separate assets will be loaded.
-	 *                                   Default false.
+	 *                                   Default false (all block assets are loaded, even when not used).
 	 */
 	return apply_filters( 'should_load_separate_core_block_assets', false );
 }

Original file line number	Diff line number	Diff line change
`@@ -2326,16 +2326,16 @@ function wp_should_load_block_editor_scripts_and_styles() {`
`2326`	`2326`	`}`
`2327`	`2327`
`2328`	`2328`	`/**`
`2329`		`- * Checks whether separate assets should be loaded for core blocks on-render.`
	`2329`	`+ * Checks whether separate styles should be loaded for core blocks on-render.`
`2330`	`2330`	`*`
`2331`	`2331`	`* When this function returns true, other functions ensure that core blocks`
`2332`		`- * only load their styles on-render, and each block loads its own, individual`
`2333`		`- * stylesheet. Third-party blocks only load their styles when rendered.`
	`2332`	`+ * only load their assets on-render, and each block loads its own, individual`
	`2333`	`+ * assets. Third-party blocks only load their assets when rendered.`
`2334`	`2334`	`*`
`2335`		`- * When this function returns false, all core block styles are loaded regardless`
	`2335`	`+ * When this function returns false, all core block assets are loaded regardless`
`2336`	`2336`	`* of whether they are rendered in a page or not, because they are all part of`
`2337`		- * the `block-library/style.css` file. Third-party blocks always get enqueued
`2338`		`- * regardless of whether they are rendered or not.`
	`2337`	+ * the `block-library/style.css` file. Assets for third-party blocks are always
	`2338`	`+ * enqueued regardless of whether they are rendered or not.`
`2339`	`2339`	`*`
`2340`	`2340`	`* This only affects front end and not the block editor screens.`
`2341`	`2341`	`*`
`@@ -2352,13 +2352,15 @@ function wp_should_load_separate_core_block_assets() {`
`2352`	`2352`	`}`
`2353`	`2353`
`2354`	`2354`	`/**`
`2355`		`- * Filters the flag that decides whether separate scripts and styles`
`2356`		`- * will be loaded for core blocks on-render.`
	`2355`	`+ * Filters whether block styles should be loaded separately.`
	`2356`	`+ *`
	`2357`	`+ * Returning false loads all core block assets, regardless of whether they are rendered`
	`2358`	`+ * in a page or not. Returning true loads core block assets only when they are rendered.`
`2357`	`2359`	`*`
`2358`	`2360`	`* @since 5.8.0`
`2359`	`2361`	`*`
`2360`	`2362`	`* @param bool $load_separate_assets Whether separate assets will be loaded.`
`2361`		`- * Default false.`
	`2363`	`+ * Default false (all block assets are loaded, even when not used).`
`2362`	`2364`	`*/`
`2363`	`2365`	`return apply_filters( 'should_load_separate_core_block_assets', false );`
`2364`	`2366`	`}`