Docs: Standardise the format used for documenting parameters passed by reference.

See #35974, #41017

Built from https://develop.svn.wordpress.org/trunk@41688


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

wp-admin/includes/class-walker-category-checklist.php

@@ -27,7 +27,7 @@ class Walker_Category_Checklist extends Walker {
 	 *
 	 * @since 2.5.1
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param int    $depth  Depth of category. Used for tab indentation.
 	 * @param array  $args   An array of arguments. @see wp_terms_checklist()
 	 */
@@ -43,7 +43,7 @@ class Walker_Category_Checklist extends Walker {
 	 *
 	 * @since 2.5.1
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param int    $depth  Depth of category. Used for tab indentation.
 	 * @param array  $args   An array of arguments. @see wp_terms_checklist()
 	 */
@@ -59,7 +59,7 @@ class Walker_Category_Checklist extends Walker {
 	 *
 	 * @since 2.5.1
 	 *
-	 * @param string $output   Passed by reference. Used to append additional content.
+	 * @param string $output   Used to append additional content (passed by reference).
 	 * @param object $category The current term object.
 	 * @param int    $depth    Depth of the term in reference to parents. Default 0.
 	 * @param array  $args     An array of arguments. @see wp_terms_checklist()
@@ -114,7 +114,7 @@ class Walker_Category_Checklist extends Walker {
 	 *
 	 * @since 2.5.1
 	 *
-	 * @param string $output   Passed by reference. Used to append additional content.
+	 * @param string $output   Used to append additional content (passed by reference).
 	 * @param object $category The current term object.
 	 * @param int    $depth    Depth of the term in reference to parents. Default 0.
 	 * @param array  $args     An array of arguments. @see wp_terms_checklist()

wp-admin/includes/class-walker-nav-menu-checklist.php

@@ -31,7 +31,7 @@ class Walker_Nav_Menu_Checklist extends Walker_Nav_Menu {
 	 *
 	 * @since 3.0.0
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param int    $depth  Depth of page. Used for padding.
 	 * @param array  $args   Not used.
 	 */
@@ -47,7 +47,7 @@ class Walker_Nav_Menu_Checklist extends Walker_Nav_Menu {
 	 *
 	 * @since 3.0.0
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param int    $depth  Depth of page. Used for padding.
 	 * @param array  $args   Not used.
 	 */
@@ -65,7 +65,7 @@ class Walker_Nav_Menu_Checklist extends Walker_Nav_Menu {
 	 *
 	 * @global int $_nav_menu_placeholder
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param object $item   Menu item data object.
 	 * @param int    $depth  Depth of menu item. Used for padding.
 	 * @param array  $args   Not used.

wp-admin/includes/class-walker-nav-menu-edit.php

@@ -49,7 +49,7 @@ class Walker_Nav_Menu_Edit extends Walker_Nav_Menu {
 	 *
 	 * @global int $_wp_nav_menu_max_depth
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param object $item   Menu item data object.
 	 * @param int    $depth  Depth of menu item. Used for padding.
 	 * @param array  $args   Not used.

wp-admin/includes/credits.php

@@ -55,7 +55,7 @@ function wp_credits() {
  * @access private
  * @since 3.2.0
  *
- * @param string $display_name  The contributor's display name, passed by reference.
+ * @param string $display_name  The contributor's display name (passed by reference).
  * @param string $username      The contributor's username.
  * @param string $profiles      URL to the contributor's WordPress.org profile page.
  */
@@ -69,7 +69,7 @@ function _wp_credits_add_profile_link( &$display_name, $username, $profiles ) {
  * @access private
  * @since 3.2.0
  *
- * @param string $data External library data, passed by reference.
+ * @param string $data External library data (passed by reference).
  */
 function _wp_credits_build_object_link( &$data ) {
 	$data = '<a href="' . esc_url( $data[1] ) . '">' . esc_html( $data[0] ) . '</a>';

wp-includes/cache.php

@@ -112,8 +112,8 @@ function wp_cache_flush() {
  * @param string      $group  Optional. Where the cache contents are grouped. Default empty.
  * @param bool        $force  Optional. Whether to force an update of the local cache from the persistent
  *                            cache. Default false.
- * @param bool        $found  Optional. Whether the key was found in the cache. Disambiguates a return of false,
- *                            a storable value. Passed by reference. Default null.
+ * @param bool        $found  Optional. Whether the key was found in the cache (passed by reference).
+ *                            Disambiguates a return of false, a storable value. Default null.
  * @return bool|mixed False on failure to retrieve contents or the cache
  *		              contents on success
  */
@@ -516,8 +516,8 @@ class WP_Object_Cache {
 	 * @param string     $group  Optional. Where the cache contents are grouped. Default 'default'.
 	 * @param string     $force  Optional. Unused. Whether to force a refetch rather than relying on the local
 	 *                           cache. Default false.
-	 * @param bool       $found  Optional. Whether the key was found in the cache. Disambiguates a return of
-	 *                           false, a storable value. Passed by reference. Default null.
+	 * @param bool        $found  Optional. Whether the key was found in the cache (passed by reference).
+	 *                            Disambiguates a return of false, a storable value. Default null.
 	 * @return false|mixed False on failure to retrieve contents or the cache contents on success.
 	 */
 	public function get( $key, $group = 'default', $force = false, &$found = null ) {

wp-includes/class-walker-category-dropdown.php

@@ -44,7 +44,7 @@ class Walker_CategoryDropdown extends Walker {
 	 *
 	 * @see Walker::start_el()
 	 *
-	 * @param string $output   Passed by reference. Used to append additional content.
+	 * @param string $output   Used to append additional content (passed by reference).
 	 * @param object $category Category data object.
 	 * @param int    $depth    Depth of category. Used for padding.
 	 * @param array  $args     Uses 'selected', 'show_count', and 'value_field' keys, if they exist.

wp-includes/class-walker-category.php

@@ -84,7 +84,7 @@ class Walker_Category extends Walker {
 	 *
 	 * @see Walker::start_el()
 	 *
-	 * @param string $output   Passed by reference. Used to append additional content.
+	 * @param string $output   Used to append additional content (passed by reference).
 	 * @param object $category Category data object.
 	 * @param int    $depth    Optional. Depth of category in reference to parents. Default 0.
 	 * @param array  $args     Optional. An array of arguments. See wp_list_categories(). Default empty array.
@@ -213,7 +213,7 @@ class Walker_Category extends Walker {
 	 *
 	 * @see Walker::end_el()
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param object $page   Not used.
 	 * @param int    $depth  Optional. Depth of category. Not used.
 	 * @param array  $args   Optional. An array of arguments. Only uses 'list' for whether should append

wp-includes/class-walker-comment.php

@@ -45,7 +45,7 @@ class Walker_Comment extends Walker {
 	 * @see Walker::start_lvl()
 	 * @global int $comment_depth
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param int    $depth  Optional. Depth of the current comment. Default 0.
 	 * @param array  $args   Optional. Uses 'style' argument for type of HTML list. Default empty array.
 	 */
@@ -73,7 +73,7 @@ class Walker_Comment extends Walker {
 	 * @see Walker::end_lvl()
 	 * @global int $comment_depth
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param int    $depth  Optional. Depth of the current comment. Default 0.
 	 * @param array  $args   Optional. Will only append content if style argument value is 'ol' or 'ul'.
 	 *                       Default empty array.

wp-includes/class-walker-nav-menu.php

@@ -43,7 +43,7 @@ class Walker_Nav_Menu extends Walker {
 	 *
 	 * @see Walker::start_lvl()
 	 *
-	 * @param string   $output Passed by reference. Used to append additional content.
+	 * @param string   $output Used to append additional content (passed by reference).
 	 * @param int      $depth  Depth of menu item. Used for padding.
 	 * @param stdClass $args   An object of wp_nav_menu() arguments.
 	 */
@@ -82,7 +82,7 @@ class Walker_Nav_Menu extends Walker {
 	 *
 	 * @see Walker::end_lvl()
 	 *
-	 * @param string   $output Passed by reference. Used to append additional content.
+	 * @param string   $output Used to append additional content (passed by reference).
 	 * @param int      $depth  Depth of menu item. Used for padding.
 	 * @param stdClass $args   An object of wp_nav_menu() arguments.
 	 */
@@ -106,7 +106,7 @@ class Walker_Nav_Menu extends Walker {
 	 *
 	 * @see Walker::start_el()
 	 *
-	 * @param string   $output Passed by reference. Used to append additional content.
+	 * @param string   $output Used to append additional content (passed by reference).
 	 * @param WP_Post  $item   Menu item data object.
 	 * @param int      $depth  Depth of menu item. Used for padding.
 	 * @param stdClass $args   An object of wp_nav_menu() arguments.
@@ -245,7 +245,7 @@ class Walker_Nav_Menu extends Walker {
 	 *
 	 * @see Walker::end_el()
 	 *
-	 * @param string   $output Passed by reference. Used to append additional content.
+	 * @param string   $output Used to append additional content (passed by reference).
 	 * @param WP_Post  $item   Page data object. Not used.
 	 * @param int      $depth  Depth of page. Not Used.
 	 * @param stdClass $args   An object of wp_nav_menu() arguments.

wp-includes/class-walker-page.php

@@ -44,7 +44,7 @@ class Walker_Page extends Walker {
 	 *
 	 * @see Walker::start_lvl()
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param int    $depth  Optional. Depth of page. Used for padding. Default 0.
 	 * @param array  $args   Optional. Arguments for outputting the next level.
 	 *                       Default empty array.
@@ -68,7 +68,7 @@ class Walker_Page extends Walker {
 	 *
 	 * @see Walker::end_lvl()
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param int    $depth  Optional. Depth of page. Used for padding. Default 0.
 	 * @param array  $args   Optional. Arguments for outputting the end of the current level.
 	 *                       Default empty array.

wp-includes/class-wp-meta-query.php

@@ -381,7 +381,7 @@ class WP_Meta_Query {
 	 *
 	 * @since 4.1.0
 	 *
-	 * @param array $query Query to parse, passed by reference.
+	 * @param array $query Query to parse (passed by reference).
 	 * @param int   $depth Optional. Number of tree levels deep we currently are.
 	 *                     Used to calculate indentation. Default 0.
 	 * @return array {
@@ -466,7 +466,7 @@ class WP_Meta_Query {
 	 *
 	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
-	 * @param array  $clause       Query clause, passed by reference.
+	 * @param array  $clause       Query clause (passed by reference).
 	 * @param array  $parent_query Parent query array.
 	 * @param string $clause_key   Optional. The array key used to name the clause in the original `$meta_query`
 	 *                             parameters. If not provided, a key will be generated automatically.

wp-includes/class-wp-query.php

@@ -2751,7 +2751,7 @@ class WP_Query {
 		 *
 		 * @param array|null $posts Return an array of post data to short-circuit WP's query,
 		 *                          or null to allow WP to run its normal queries.
-		 * @param WP_Query   $this  The WP_Query instance, passed by reference.
+		 * @param WP_Query   $this  The WP_Query instance (passed by reference).
 		 */
 		$this->posts = apply_filters_ref_array( 'posts_pre_query', array( null, &$this ) );
 

wp-includes/class-wp-rewrite.php

@@ -1392,7 +1392,7 @@ class WP_Rewrite {
 		 *
 		 * @since 1.5.0
 		 *
-		 * @param WP_Rewrite $this Current WP_Rewrite instance, passed by reference.
+		 * @param WP_Rewrite $this Current WP_Rewrite instance (passed by reference).
 		 */
 		do_action_ref_array( 'generate_rewrite_rules', array( &$this ) );
 

wp-includes/class-wp-tax-query.php

@@ -291,7 +291,7 @@ class WP_Tax_Query {
 	 *
 	 * @since 4.1.0
 	 *
-	 * @param array $query Query to parse, passed by reference.
+	 * @param array $query Query to parse (passed by reference).
 	 * @param int   $depth Optional. Number of tree levels deep we currently are.
 	 *                     Used to calculate indentation. Default 0.
 	 * @return array {
@@ -374,7 +374,7 @@ class WP_Tax_Query {
 	 *
 	 * @global wpdb $wpdb The WordPress database abstraction object.
 	 *
-	 * @param array $clause       Query clause, passed by reference.
+	 * @param array $clause       Query clause (passed by reference).
 	 * @param array $parent_query Parent query array.
 	 * @return array {
 	 *     Array containing JOIN and WHERE SQL clauses to append to a first-order query.

wp-includes/class-wp-theme.php

@@ -1426,7 +1426,7 @@ final class WP_Theme implements ArrayAccess {
 	 *
 	 * @static
 	 *
-	 * @param array $themes Array of themes to sort, passed by reference.
+	 * @param array $themes Array of themes to sort (passed by reference).
 	 */
 	public static function sort_by_name( &$themes ) {
 		if ( 0 === strpos( get_user_locale(), 'en_' ) ) {

wp-includes/class-wp-walker.php

@@ -55,7 +55,7 @@ class Walker {
 	 * @since 2.1.0
 	 * @abstract
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param int    $depth  Depth of the item.
 	 * @param array  $args   An array of additional arguments.
 	 */
@@ -70,7 +70,7 @@ class Walker {
 	 * @since 2.1.0
 	 * @abstract
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param int    $depth  Depth of the item.
 	 * @param array  $args   An array of additional arguments.
 	 */
@@ -85,7 +85,7 @@ class Walker {
 	 * @since 2.1.0
 	 * @abstract
 	 *
-	 * @param string $output            Passed by reference. Used to append additional content.
+	 * @param string $output            Used to append additional content (passed by reference).
 	 * @param object $object            The data object.
 	 * @param int    $depth             Depth of the item.
 	 * @param array  $args              An array of additional arguments.
@@ -101,7 +101,7 @@ class Walker {
 	 * @since 2.1.0
 	 * @abstract
 	 *
-	 * @param string $output Passed by reference. Used to append additional content.
+	 * @param string $output Used to append additional content (passed by reference).
 	 * @param object $object The data object.
 	 * @param int    $depth  Depth of the item.
 	 * @param array  $args   An array of additional arguments.
@@ -121,11 +121,11 @@ class Walker {
 	 * @since 2.5.0
 	 *
 	 * @param object $element           Data object.
-	 * @param array  $children_elements List of elements to continue traversing.
+	 * @param array  $children_elements List of elements to continue traversing (passed by reference).
 	 * @param int    $max_depth         Max depth to traverse.
 	 * @param int    $depth             Depth of current element.
 	 * @param array  $args              An array of arguments.
-	 * @param string $output            Passed by reference. Used to append additional content.
+	 * @param string $output            Used to append additional content (passed by reference).
 	 */
 	public function display_element( $element, &$children_elements, $max_depth, $depth, $args, &$output ) {
 		if ( ! $element ) {

wp-includes/class-wp-widget.php

@@ -518,7 +518,7 @@ class WP_Widget {
 			 *
 			 * @since 2.8.0
 			 *
-			 * @param WP_Widget $this     The widget instance, passed by reference.
+			 * @param WP_Widget $this     The widget instance (passed by reference).
 			 * @param null      $return   Return null if new fields are added.
 			 * @param array     $instance An array of the widget's settings.
 			 */

wp-includes/ms-functions.php

@@ -2159,7 +2159,7 @@ function add_new_user_to_blog( $user_id, $password, $meta ) {
  *
  * @since MU (3.0.0)
  *
- * @param PHPMailer $phpmailer The PHPMailer instance, passed by reference.
+ * @param PHPMailer $phpmailer The PHPMailer instance (passed by reference).
  */
 function fix_phpmailer_messageid( $phpmailer ) {
 	$phpmailer->Hostname = get_network()->domain;

wp-includes/post.php

@@ -4448,7 +4448,7 @@ function get_page_children( $page_id, $pages ) {
  *
  * @since 2.0.0
  *
- * @param array $pages   Posts array, passed by reference.
+ * @param array $pages   Posts array (passed by reference).
  * @param int   $page_id Optional. Parent page ID. Default 0.
  * @return array A list arranged by hierarchy. Children immediately follow their parents.
  */
@@ -4479,8 +4479,8 @@ function get_page_hierarchy( &$pages, $page_id = 0 ) {
  * @see _page_traverse_name()
  *
  * @param int   $page_id   Page ID.
- * @param array $children  Parent-children relations, passed by reference.
- * @param array $result    Result, passed by reference.
+ * @param array $children  Parent-children relations (passed by reference).
+ * @param array $result    Result (passed by reference).
  */
 function _page_traverse_name( $page_id, &$children, &$result ){
 	if ( isset( $children[ $page_id ] ) ){
@@ -5731,7 +5731,7 @@ function _get_last_post_time( $timezone, $field, $post_type = 'any' ) {
  *
  * @since 1.5.1
  *
- * @param array $posts Array of post objects, passed by reference.
+ * @param array $posts Array of post objects (passed by reference).
  */
 function update_post_cache( &$posts ) {
 	if ( ! $posts )

wp-includes/taxonomy.php

@@ -3324,7 +3324,7 @@ function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array()
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param array  $terms    List of term objects, passed by reference.
+ * @param array  $terms    List of term objects (passed by reference).
  * @param string $taxonomy Term context.
  */
 function _pad_term_counts( &$terms, $taxonomy ) {

wp-includes/user.php

@@ -57,8 +57,8 @@ function wp_signon( $credentials = array(), $secure_cookie = '' ) {
 	 *
 	 * @todo Decide whether to deprecate the wp_authenticate action.
 	 *
-	 * @param string $user_login    Username, passed by reference.
-	 * @param string $user_password User password, passed by reference.
+	 * @param string $user_login    Username (passed by reference).
+	 * @param string $user_password User password (passed by reference).
 	 */
 	do_action_ref_array( 'wp_authenticate', array( &$credentials['user_login'], &$credentials['user_password'] ) );
 

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.9-alpha-41687';
+$wp_version = '4.9-alpha-41688';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.