WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 4 years ago

Last modified 4 years ago

#33912 closed defect (bug) (fixed)

Document the various optional parameter permutations of add_query_arg()

Reported by: DrewAPicture Owned by: DrewAPicture
Milestone: 4.4 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs Cc:
PR Number:

Description

As we did in #32694 for current_user_can(), we should also attempt to document the various optional parameter permutations possible with add_query_arg().

add_query_arg(), however, is a tougher nut to crack because unlike current_user_can() and some others, it has no default signature, just an interesting mix of possible uses.

I would also like to look at improving the naming of the parameters for the existing documentation. $param1, $param2, and $param3 is pretty terrible.

Attachments (2)

33912.patch (2.7 KB) - added by johnbillion 4 years ago.
33912.2.patch (3.0 KB) - added by DrewAPicture 4 years ago.

Download all attachments as: .zip

Change History (9)

#1 @DrewAPicture
4 years ago

In 34264:

Docs: Add a reminder to the DocBlock description for add_query_arg() mentioning that the output is not escaped by default.

Props brentvr for the initial patch. (first props!)
See #33912. See #32246.

#2 @DrewAPicture
4 years ago

  • Milestone changed from Awaiting Review to Future Release

@johnbillion
4 years ago

#3 @johnbillion
4 years ago

  • Keywords has-patch added; needs-patch removed

I briefly discussed variadic function documentation with @DrewAPicture, but it turns out that it's not at all helpful when describing a function such as this, which isn't so much variadic as it's just got multiple call signatures.

33912.patch is an attempt at improving the parameter names and descriptions, and adding example uses. Feedback appreciated.

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


4 years ago

#5 @DrewAPicture
4 years ago

In 34511:

Docs: Overhaul the DocBlock for add_query_arg() to attempt to better explain the various call signatures it accepts.

Also adds a couple of in-DocBlock examples illustrating single key and value, and associative array usage. Retains the note about the unescaped return value.

Props johnbillion.
See #33912.

#6 @DrewAPicture
4 years ago

  • Owner set to DrewAPicture
  • Resolution set to fixed
  • Status changed from new to closed

In 34512:

Docs: Clarify the summary and optional $query parameter description for remove_query_arg().

Props johnbillion.
Fixes #33912.

#7 @netweb
4 years ago

  • Milestone changed from Future Release to 4.4
Note: See TracTickets for help on using tickets.