Editor: Some documentation and test improvements for loading separate assets for core blocks:

* Move `should_load_separate_core_block_assets()` to a more appropriate place.
* Update DocBlocks and inline comments per the documentation standards.
* Document the `$wp_styles` global in `wp_maybe_inline_styles()`.
* List the expected result first in unit test assertions.
* Remove a duplicate unit test.
* Add missing `@covers` tags.

Follow-up to [50836], [50837].

See #50328, #52620, #53180.
Built from https://develop.svn.wordpress.org/trunk@50838


git-svn-id: http://core.svn.wordpress.org/trunk@50447 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/script-loader.php

@@ -1364,29 +1364,6 @@ function wp_default_scripts( $scripts ) {
 	}
 }
 
-/**
- * Checks whether separate assets should be loaded for core blocks.
- *
- * @since 5.8
- *
- * @return bool
- */
-function should_load_separate_core_block_assets() {
-	if ( is_admin() || is_feed() || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
-		return false;
-	}
-	/**
-	 * Determine if separate styles & scripts will be loaded for blocks on-render or not.
-	 *
-	 * @since 5.8.0
-	 *
-	 * @param bool $load_separate_styles Whether separate styles will be loaded or not.
-	 *
-	 * @return bool Whether separate styles will be loaded or not.
-	 */
-	return apply_filters( 'separate_core_block_assets', false );
-}
-
 /**
  * Assign default styles to $styles object.
  *
@@ -2276,7 +2253,7 @@ function wp_common_block_scripts_and_styles() {
  *
  * @since 5.6.0
  *
- * @return bool
+ * @return bool Whether scripts and styles should be enqueued.
  */
 function wp_should_load_block_editor_scripts_and_styles() {
 	global $current_screen;
@@ -2284,8 +2261,8 @@ function wp_should_load_block_editor_scripts_and_styles() {
 	$is_block_editor_screen = ( $current_screen instanceof WP_Screen ) && $current_screen->is_block_editor();
 
 	/**
-	 * Filters the flag that decides whether or not block editor scripts and
-	 * styles are going to be enqueued on the current screen.
+	 * Filters the flag that decides whether or not block editor scripts and styles
+	 * are going to be enqueued on the current screen.
 	 *
 	 * @since 5.6.0
 	 *
@@ -2294,6 +2271,30 @@ function wp_should_load_block_editor_scripts_and_styles() {
 	return apply_filters( 'should_load_block_editor_scripts_and_styles', $is_block_editor_screen );
 }
 
+/**
+ * Checks whether separate assets should be loaded for core blocks on-render.
+ *
+ * @since 5.8.0
+ *
+ * @return bool Whether separate assets will be loaded or not.
+ */
+function should_load_separate_core_block_assets() {
+	if ( is_admin() || is_feed() || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
+		return false;
+	}
+
+	/**
+	 * Filters the flag that decides whether or not separate scripts and styles
+	 * will be loaded for core blocks on-render or not.
+	 *
+	 * @since 5.8.0
+	 *
+	 * @param bool $load_separate_assets Whether separate assets will be loaded or not.
+	 *                                   Default false.
+	 */
+	return apply_filters( 'separate_core_block_assets', false );
+}
+
 /**
  * Enqueues registered block scripts and styles, depending on current rendered
  * context (only enqueuing editor scripts while in context of the editor).
@@ -2529,28 +2530,28 @@ function wp_print_inline_script_tag( $javascript, $attributes = array() ) {
 }
 
 /**
- * Allow small styles to be inlined.
- * This improves performance and sustainability, and is opt-in.
+ * Allows small styles to be inlined.
  *
- * Stylesheets can opt-in by adding `path` data using `wp_style_add_data`, and defining the file's absolute path.
- * wp_style_add_data( $style_handle, 'path', $file_path );
+ * This improves performance and sustainability, and is opt-in. Stylesheets can opt in
+ * by adding `path` data using `wp_style_add_data`, and defining the file's absolute path:
+ *
+ *     wp_style_add_data( $style_handle, 'path', $file_path );
  *
  * @since 5.8.0
  *
- * @return void
+ * @global WP_Styles $wp_styles
  */
 function wp_maybe_inline_styles() {
+	global $wp_styles;
 
 	$total_inline_limit = 20000;
 	/**
 	 * The maximum size of inlined styles in bytes.
 	 *
 	 * @param int $total_inline_limit The file-size threshold, in bytes. Defaults to 20000.
-	 * @return int                    The file-size threshold, in bytes.
 	 */
 	$total_inline_limit = apply_filters( 'styles_inline_size_limit', $total_inline_limit );
 
-	global $wp_styles;
 	$styles = array();
 
 	// Build an array of styles that have a path defined.
@@ -2573,7 +2574,7 @@ function wp_maybe_inline_styles() {
 			}
 		);
 
-		/**
+		/*
 		 * The total inlined size.
 		 *
 		 * On each iteration of the loop, if a style gets added inline the value of this var increases

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.8-alpha-50837';
+$wp_version = '5.8-alpha-50838';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.