From c805479c8b5d6e1aa231596c18969a1e447b4740 Mon Sep 17 00:00:00 2001
From: Gary Pendergast <gary@pento.net>
Date: Thu, 28 Sep 2017 11:45:45 +0000
Subject: [PATCH] Docs: Update the documentation for `wpdb::prepare()`

The inline documentation for `wpdb::prepare()` was kind of confusing, and didn't describe some of the behaviour correctly.

Fixes #41983.


Built from https://develop.svn.wordpress.org/trunk@41632


git-svn-id: http://core.svn.wordpress.org/trunk@41467 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/version.php |  2 +-
 wp-includes/wp-db.php   | 28 +++++++++++++---------------
 2 files changed, 14 insertions(+), 16 deletions(-)

diff --git a/wp-includes/version.php b/wp-includes/version.php
index 27f4c97a25..12a43dab96 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.9-alpha-41631';
+$wp_version = '4.9-alpha-41632';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
diff --git a/wp-includes/wp-db.php b/wp-includes/wp-db.php
index e96714fa23..89af746988 100644
--- a/wp-includes/wp-db.php
+++ b/wp-includes/wp-db.php
@@ -1194,35 +1194,33 @@ class wpdb {
 	/**
 	 * Prepares a SQL query for safe execution. Uses sprintf()-like syntax.
 	 *
-	 * The following directives can be used in the query format string:
+	 * The following placeholders can be used in the query string:
 	 *   %d (integer)
 	 *   %f (float)
 	 *   %s (string)
-	 *   %% (literal percentage sign - no argument needed)
 	 *
-	 * All of %d, %f, and %s are to be left unquoted in the query string and they need an argument passed for them.
-	 * Literals (%) as parts of the query must be properly written as %%.
+	 * All placeholders MUST be left unquoted in the query string. A corresponding argument MUST be passed for each placeholder.
 	 *
-	 * This function only supports a small subset of the sprintf syntax; it only supports %d (integer), %f (float), and %s (string).
-	 * Does not support sign, padding, alignment, width or precision specifiers.
-	 * Does not support argument numbering/swapping.
+	 * Literal percentage signs (%) in the query string must be written as %%. Percentage wildcards (for example, to use in LIKE syntax)
+	 * must be passed in the string argument, it cannot be inserted in the query string.
 	 *
-	 * May be called like {@link https://secure.php.net/sprintf sprintf()} or like {@link https://secure.php.net/vsprintf vsprintf()}.
+	 * This method DOES NOT support sign, padding, alignment, width or precision specifiers.
+	 * This method DOES NOT support argument numbering or swapping.
 	 *
-	 * Both %d and %s should be left unquoted in the query string.
+	 * Arguments may be passed as individual arguments to the method, or as a single array containing all arguments. A combination 
+	 * of the two is not supported.
 	 *
-	 *     $wpdb->prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d", 'foo', 1337 );
+	 * Examples:
+	 *     $wpdb->prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d OR `other_field` LIKE %s", array( 'foo', 1337, '%bar' ) );
 	 *     $wpdb->prepare( "SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo' );
 	 *
 	 * @link https://secure.php.net/sprintf Description of syntax.
 	 * @since 2.3.0
 	 *
 	 * @param string      $query    Query statement with sprintf()-like placeholders
-	 * @param array|mixed $args     The array of variables to substitute into the query's placeholders if being called like
-	 *                              {@link https://secure.php.net/vsprintf vsprintf()}, or the first variable to substitute into the query's placeholders if
-	 *                              being called like {@link https://secure.php.net/sprintf sprintf()}.
-	 * @param mixed       $args,... further variables to substitute into the query's placeholders if being called like
-	 *                              {@link https://secure.php.net/sprintf sprintf()}.
+	 * @param array|mixed $args     The array of variables to substitute into the query's placeholders if being called with an array of arguments,
+	 *                              or the first variable to substitute into the query's placeholders if being called with individual arguments.
+	 * @param mixed       $args,... further variables to substitute into the query's placeholders if being called wih individual arguments.
 	 * @return string|void Sanitized query string, if there is a query to prepare.
 	 */
 	public function prepare( $query, $args ) {