build_query() docblock incorrectly states it URL-encodes its data

[nimeshatxecurify]

Problem

The docblock for build_query() in src/wp-includes/functions.php claims the function URL-encodes its input and returns a URL-encoded string. It does not.

build_query() calls _http_build_query() with $urlencode = false:

<?php
function build_query( $data ) {
    return _http_build_query( $data, null, '&', '', false );
}

So no urlencode() / rawurlencode() is applied to keys or values. The current docblock is misleading:

@param  array  $data URL-encode key/value pairs.
@return string       URL-encoded string.

Why this matters

This incorrect documentation is the recurring source of confusion behind the long-standing reports that add_query_arg() "should encode but doesn't":

• #17923 – add_query_arg() should encode values
• #46966 – urlencode query string parameters

In #17923 comment:25, ​@johnbillion noted the same confusion directly:

I'd be interested to know what the following code in add_query_arg() does. It appears to encode the URL's query arguments, but evidently doesn't.

add_query_arg() relies on build_query() to serialize the query string, and because build_query() does not encode, newly-added keys/values come out raw. That behavior is by design (changing it would break backward
compatibility, and output is expected to be late-escaped with esc_url()), but the build_query() docblock actively misrepresents it.

Steps to reproduce

<?php
echo build_query( array( 'foo' => 'this & that' ) );
// Actual:            foo=this & that
// Docblock implies:  foo=this+%26+that

Proposed fix

Documentation-only. Correct the @param and @return descriptions to state that build_query() does not URL-encode (unlike PHP's native http_build_query()), and that callers are responsible for encoding values
beforehand or late-escaping output with esc_url().

No change to function behavior — this is intentionally backward-compatible.

Notes

This ticket is split out from the discussion on #17923 and #46966 to track the documentation bug independently of those (effectively wontfix / by-design) behavior-change requests.

The documentation for build_query() incorrectly indicated that the function URL-encodes its output. This updates the docblock to clarify that, unlike PHP's native http_build_query(), this function does not perform encoding. Callers are responsible for encoding values beforehand or escaping the output late.