Changeset 50265 for trunk/tests/phpunit/includes/utils.php

Timestamp:

02/09/2021 01:22:47 PM (4 years ago)

Author:

johnbillion

Message:

Build/Test Tools: Various docblock improvements within test utilities.

See #51802

File:

• trunk/tests/phpunit/includes/utils.php (modified) (5 diffs)

trunk/tests/phpunit/includes/utils.php

@@ -3 +3 @@
 // Misc help functions and utilities.
 
+/**
+ * Returns a string of the required length containing random characters. Note that
+ * the maximum possible string length is 32.
+ *
+ * @param int $len Optional. The required length. Default 32.
+ * @return string The string.
+ */
 function rand_str( $len = 32 ) {
     return substr( md5( uniqid( rand() ) ), 0, $len );
 }
 
+/**
+ * Returns a string of the required length containing random characters.
+ *
+ * @param int $len The required length.
+ * @return string The string.
+ */
 function rand_long_str( $length ) {
     $chars  = 'abcdefghijklmnopqrstuvwxyz';
@@ -19 +32 @@
 }
 
-// Strip leading and trailing whitespace from each line in the string.
+/**
+ * Strips leading and trailing whitespace from each line in the string.
+ *
+ * @param string $txt The text.
+ * @return string Text with line-leading and line-trailing whitespace stripped.
+ */
 function strip_ws( $txt ) {
     $lines  = explode( "\n", $txt );
@@ -34 +52 @@
 /*
  * Helper class for testing code that involves actions and filters.
+ *
  * Typical use:
- * $ma = new MockAction();
- * add_action( 'foo', array( &$ma, 'action' ) );
+ *
+ *     $ma = new MockAction();
+ *     add_action( 'foo', array( &$ma, 'action' ) );
  */
 class MockAction {
@@ -241 +261 @@
 }
 
+/**
+ * Converts an XML string into an array tree structure.
+ *
+ * The output of this function can be passed to xml_find() to find nodes by their path.
+ *
+ * @param string $in The XML string.
+ * @return array XML as an array.
+ */
 function xml_to_array( $in ) {
     $p = new TestXMLParser( $in );
@@ -246 +274 @@
 }
 
+/**
+ * Finds XML nodes by a given "path".
+ *
+ * Example usage:
+ *
+ *     $tree = xml_to_array( $rss );
+ *     $items = xml_find( $tree, 'rss', 'channel', 'item' );
+ *
+ * @param array     $tree     An array tree structure of XML, typically from xml_to_array().
+ * @param string ...$elements Names of XML nodes to create a "path" to find within the XML.
+ * @return array Array of matching XML node information.
+ */
 function xml_find( $tree, ...$elements ) {
     $n   = count( $elements );