Document the various optional parameter permutations of add_query_arg()

[DrewAPicture]

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.

[DrewAPicture]

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.

[johnbillion]

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.

[DrewAPicture]

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.

[DrewAPicture]

In 34512:

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

Props johnbillion.
Fixes #33912.