General: Some documentation and test improvements for the `_wp_array_set()`:

* Update the function DocBlock per the documentation standards.
* Move the unit tests to a more appropriate place.
* Rename and reorder the tests for consistency with `_wp_array_get()` tests.

Follow-up to [50958], [50962], [50964].

See #53175, #52625.
Built from https://develop.svn.wordpress.org/trunk@50965


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

wp-includes/functions.php

@@ -4636,6 +4636,7 @@ function _wp_array_get( $array, $path, $default = null ) {
  *
  *     $array = array();
  *     _wp_array_set( $array, array( 'a', 'b', 'c', 1 );
+ *
  *     $array becomes:
  *     array(
  *         'a' => array(
@@ -4645,6 +4646,11 @@ function _wp_array_get( $array, $path, $default = null ) {
  *         ),
  *     );
  *
+ * @internal
+ *
+ * @since 5.8.0
+ * @access private
+ *
  * @param array $array An array that we want to mutate to include a specific value in a path.
  * @param array $path  An array of keys describing the path that we want to mutate.
  * @param mixed $value The value that will be set.
@@ -4659,10 +4665,13 @@ function _wp_array_set( &$array, $path, $value = null ) {
 	if ( ! is_array( $path ) ) {
 		return;
 	}
+
 	$path_length = count( $path );
+
 	if ( 0 === $path_length ) {
 		return;
 	}
+
 	foreach ( $path as $path_element ) {
 		if (
 			! is_string( $path_element ) && ! is_integer( $path_element ) &&
@@ -4682,6 +4691,7 @@ function _wp_array_set( &$array, $path, $value = null ) {
 		}
 		$array = &$array[ $path_element ]; // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.VariableRedeclaration
 	}
+
 	$array[ $path[ $i ] ] = $value;
 }
 

wp-includes/version.php

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