Changeset 37877 for trunk/src/wp-includes/query.php

Timestamp:

06/26/2016 05:46:10 PM (8 years ago)

Author:

DrewAPicture

Message:

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.

File:

• trunk/src/wp-includes/query.php (modified) (2 diffs)

trunk/src/wp-includes/query.php

@@ -78 +78 @@
 
 /**
- * Set 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.
+ * Sets up The Loop with query parameters.
+ *
+ * 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
@@ -87 +90 @@
  * @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) {