WordPress.org

Make WordPress Core

Opened 7 weeks ago

Last modified 27 hours ago

#52264 new task (blessed)

Rename `$array` when used in `@param` tags

Reported by: audrasjb Owned by:
Milestone: 5.8 Priority: normal
Severity: normal Version:
Component: General Keywords:
Focuses: docs Cc:

Description

Related: #52243

Several functions, filters and actions pass $array as a parameter.
Usage of $array in @param tags for actions and filters should be replaced with a more appropriate (and descriptive) variable name.

Example:

In class-requests.php

/**
 * Convert a key => value array to a 'key: value' array for headers
 *
 * @param array $array Dictionary of header values
 * @return string[] List of headers
 */
public static function flatten($array) {

Could be replaced with:

/**
 * Convert a key => value array to a 'key: value' array for headers
 *
 * @param array $headers Dictionary of header values
 * @return string[] List of headers
 */
public static function flatten( $headers ) {

Change History (7)

#1 @SergeyBiryukov
7 weeks ago

Just noting that class-requests.php is not the best example here, as it's a part of the ​Requests external library, any changes there should be submitted upstream.

Otherwise, this makes sense to me :)

#2 @audrasjb
7 weeks ago

@SergeyBiryukov ah, right… I have to admit I took the first example I found πŸ˜‡

#3 @desrosj
3 weeks ago

Possible duplicate/overlap of #51553.

This ticket was mentioned in ​Slack in #core by hellofromtonya. ​View the logs.


3 weeks ago

#5 @hellofromTonya
3 weeks ago

  • Type changed from enhancement to task (blessed)

As this ticket seeks to improve code documentation, it fits better as a blessed task. In doing so, work can continue throughout the cycle.

#6 @peterwilsoncc
8 days ago

Reviewing the src directory:

  • Occurs 25 times in 11 files
  • WP_Query::fill_query_vars parameter could certainly do with a more descriptive name
  • add_magic_quotes() walks an array recursively and slashes it -- could probably be more descriptive

The following seem to be legitimate descriptive names, they do an action on a generic array

  • wp_parse_str() and filter of the same name
  • wp_array_slice_assoc()
  • _wp_array_get()
  • _rest_array_intersect_key_recursive()
  • rest_validate_array_contains_unique_items() (params $array1, $array2)

Remaining items are in libraries:

  • Requests
  • ID3
  • IXR
  • sodium compatibility

#7 @SergeyBiryukov
27 hours ago

  • Milestone changed from 5.7 to 5.8

Looks like this still needs a patch. Per the feedback above, the are some legitimate use cases and some that could be clarified. Moving to the next release for now.

Note: See TracTickets for help on using tickets.