From 60894914778c2f498ca810fbe27e921e5bac0e50 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Sun, 26 Jun 2016 17:46:10 +0000 Subject: [PATCH] Docs: Add a note to the DocBlock for `query_posts()` to caution against general usage, including a pointer to the `pre_get_posts` action. Also adds missing parameter and return descriptions. See #32246. git-svn-id: https://develop.svn.wordpress.org/trunk@37877 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/query.php | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/wp-includes/query.php b/src/wp-includes/query.php index 96d47902b8..35662468f0 100644 --- a/src/wp-includes/query.php +++ b/src/wp-includes/query.php @@ -77,17 +77,20 @@ function set_query_var( $var, $value ) { } /** - * Set up The Loop with query parameters. + * Sets up The Loop with query parameters. * - * This will override the current WordPress Loop and shouldn't be used more than - * once. This must not be used within the WordPress Loop. + * Important: This will completely override the current WordPress Loop and can easily + * produce unexpected results. In most cases, the better option is to instead modify + * specific properties of the loop using the {@see 'pre_get_posts'} action. + * + * This must not be used within the WordPress Loop. * * @since 1.5.0 * * @global WP_Query $wp_query Global WP_Query instance. * - * @param string $query - * @return array List of posts + * @param array|string $query Array or string of WP_Query arguments. + * @return array List of post objects. */ function query_posts($query) { $GLOBALS['wp_query'] = new WP_Query();