Make WordPress Core

Opened 3 years ago

Last modified 2 years ago

#52264 new task (blessed)

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

Reported by: audrasjb's profile audrasjb Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
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 (10)

#1 @SergeyBiryukov
3 years 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
3 years ago

@SergeyBiryukov ah, right… I have to admit I took the first example I found 😇

#3 @desrosj
3 years ago

Possible duplicate/overlap of #51553.

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


3 years ago

#5 @hellofromTonya
3 years 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
3 years 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
3 years 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.


3 years ago

#9 @peterwilsoncc
3 years ago

  • Milestone changed from 5.8 to Future Release

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

This ticket was mentioned in PR #2360 on WordPress/wordpress-develop by pbearne.


2 years ago
#10

  • Keywords has-patch added
Note: See TracTickets for help on using tickets.