WordPress.org

Make WordPress Core

Opened 9 months ago

Last modified 4 months ago

#52264 new task (blessed)

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

Reported by: audrasjb Owned by:
Milestone: Future Release 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 (9)

#1 @SergeyBiryukov
9 months 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
9 months ago

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

#3 @desrosj
8 months ago

Possible duplicate/overlap of #51553.

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


8 months ago

#5 @hellofromTonya
8 months 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
7 months 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
7 months 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.

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


4 months ago

#9 @peterwilsoncc
4 months ago

  • Milestone changed from 5.8 to Future Release

Punting this from 5.8 as there isn't a patch.

Note: See TracTickets for help on using tickets.