WordPress.org

Make WordPress Core

Opened 5 years ago

Closed 5 years ago

#34857 closed defect (bug) (fixed)

Improve documentation for wp_admin_css_color()

Reported by: swissspidy Owned by: kiranpotphode
Milestone: 4.5 Priority: normal
Severity: normal Version:
Component: Administration Keywords: good-first-bug has-patch commit
Focuses: docs Cc:

Description

As per the @todo comment in wp_admin_css_color(), the function's optional parameters need some love.

There's a usage example in the description, but from looking at the params alone it's not clear what exactly you can pass and what the default param (empty array) means. Also, the punctuation is not 100% correct.

See the PHP documentation standards for more details.

Attachments (2)

general-template.php.diff (1.5 KB) - added by kiranpotphode 5 years ago.
$colors array does not have any keys but accepts four parameters. So hash notations for $colors argument are missing key|value.
general-template.php.2.diff (1.4 KB) - added by kiranpotphode 5 years ago.
Documented flat array as suggested. Uploaded updated patch.

Download all attachments as: .zip

Change History (10)

#1 @swissspidy
5 years ago

  • Component changed from General to Administration

@kiranpotphode
5 years ago

$colors array does not have any keys but accepts four parameters. So hash notations for $colors argument are missing key|value.

#2 @kiranpotphode
5 years ago

  • Keywords has-patch added; needs-patch removed

Any guidelines on hash notations where arguments have no key-value pair but accepts definite number of parameters?
For example in this case $colors argument accepts 4 parameters but lacks keys for parameters.

Last edited 5 years ago by kiranpotphode (previous) (diff)

#3 follow-up: @swissspidy
5 years ago

  • Milestone changed from Awaiting Review to Future Release
  • Owner set to kiranpotphode
  • Status changed from new to assigned

Any guidelines on hash notations where arguments have no key-value pair but accepts definite number of parameters?

For example in this case $colors argument accepts 4 parameters but lacks keys for parameters.

@DrewAPicture to the rescue? :-)

#4 in reply to: ↑ 3 @DrewAPicture
5 years ago

Replying to swissspidy:

Any guidelines on hash notations where arguments have no key-value pair but accepts definite number of parameters?

For example in this case $colors argument accepts 4 parameters but lacks keys for parameters.

@DrewAPicture to the rescue? :-)

We don't document flat arrays in hash notations. I would suggest documenting the accepted values, types, and exact order required in the parameter description.

#5 @swissspidy
5 years ago

  • Keywords needs-refresh added

@kiranpotphode Do you have time to update the patch as per the suggestions above?

@kiranpotphode
5 years ago

Documented flat array as suggested. Uploaded updated patch.

#6 @swissspidy
5 years ago

  • Keywords needs-refresh removed
  • Milestone changed from Future Release to 4.5

#7 @swissspidy
5 years ago

  • Keywords commit added

#8 @SergeyBiryukov
5 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

In 36107:

Docs: Improve documentation for wp_admin_css_color().

Props kiranpotphode.
Fixes #34857.

Note: See TracTickets for help on using tickets.