Index: src/wp-includes/functions.php
===================================================================
--- src/wp-includes/functions.php	(revision 34248)
+++ src/wp-includes/functions.php	(working copy)
@@ -680,6 +680,21 @@
  * value. Additional values provided are expected to be encoded appropriately
  * with urlencode() or rawurlencode().
  *
+ *    // Both examples will output: http://www.example.com/?key=value
+ *
+ *    $param1 = 'key';
+ *    $param2 = 'value';
+ *    $param3 = 'http://www.example.com';
+ *
+ *    // Parameters as separate arguments
+ *    add_query_arg( $param1, $param2, $param3 );
+ *
+ *    // Parameters as array of key => value pairs
+ *    add_query_arg( array( $param1 => $param2 ), $param3 ); // Where param1 = 'key'
+ *
+ * Reminder: The return value of this function should be escaped on output to
+ * prevent exposure to XXS vulnerabilities using esc_url() or similar.
+ *
  * @since 1.5.0
  *
  * @param string|array $param1 Either newkey or an associative_array.