query_posts codex correct or not?

That’s a pretty good article in Codex. So use either get_posts or preferably a new WP_Query for your ‘loops’. For example:
a simple loop to query posts:

<?php
    $args=array(
      'post_type' => 'post',
      'post_status' => 'publish',
      'posts_per_page' => -1,
      'caller_get_posts'=> 1
      );
    $my_query = null;
    $my_query = new WP_Query($args);
    if( $my_query->have_posts() ) {
      echo 'List of Posts';
      while ($my_query->have_posts()) : $my_query->the_post(); ?>
      <p><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>"><?php the_title(); ?></a></p>
       <?php
      endwhile;
    }
wp_reset_query();  // Restore global post data stomped by the_post().
?>

http://codex.wordpress.org/Function_Reference

is the list of functions…..

http://codex.wordpress.org/Function_Reference/get_posts

has lots of stuff…..

I went to the query_post page which also has many parameters listed and usage examples. Can all of this be transfered into the wp_query?

Yes.

What purpose does wp_reset_query() serve if not to support multiple calls to query_posts()

Comments directly from wp-includes/query.php ..

/**
* Destroy the previous query and setup a new query.
*
* This should be used after {@link query_posts()} and before another {@link
* query_posts()}. This will remove obscure bugs that occur when the previous
* wp_query object is not destroyed properly before another is setup.
*
* @since 2.3.0
* @uses $wp_query
*/

As long as wp_reset_query is called, it should be valid to use multiple calls to query_posts should it not?

Well i can certainly understand that problems may occur as a result of re-using the main query. For example if something else on the page relies on looking at data in the “main query” (something that loads after your series of loops perhaps), it would be looking at incorrect data because the original query has changed (you can clone the original query’s data to fix things like this).

Overall i agree the advice is good, but i don’t think it’s strictly true that you can’t reuse query_posts … i’ve done so without causing any problems as far as i can observe, but if i’m making a mistake in doing so i’d be interested in a further explanation of the following..

Use of query_posts on other Loops than the main one can result in your main Loop becoming incorrect and possibly displaying things that you were not expecting.

I’d say it’s proberly good advice to use a new query, just to avoid causing problems with other queries or code that has dependancies on the main query…

In short i think the answer is… you can use multiple calls, but don’t be surprised if other things sometimes give wrong data sets as a result of re-using the main query..

I’m not intimately familiar with the WP_Query class, so i’m not sure on it’s limitations, problems or it’s correct (suggested?) usage, so i’ll happily concede to anyone who can pick my logic apart… and explain how it should be used, and why it should be used a given way…

Adding this wp-hackers thread to the conversation:
http://lists.automattic.com/pipermail/wp-hackers/2009-December/029569.html

@t31os_

Well it just seemed easier to use a new query object and not have to worry about messing up the ‘other’ query that WordPress automatically populates. Plus in testing when answering forum questions I’m usually throwing the code at the top of index.php or archive.php or sidebar.php for the Default theme and the new query just worked 😉

But you are right about the wp_reset_query and I suppose that if you know what you are doing, either approach will work.

Note – I figured you’d read that hackers thread but just added for future readers.