Inline documentation cleanup for 4.0 audit.

Various improvements:
* Adds `@see` reference for `wp_list_comments()` in 'wp_list_comments_args' filter docs, added in [28285]
* Various phpDoc tweaks for the 'run_wptexturize' filter docs, added in [28715]
* Sentence and wrapping changes for `is_https_url()`, added in [28894]
* Documents the `$args` parameter for `wp_dropdown_languages()`, added in [29007]
* Adds a period to the parameter description for `_update_posts_count_on_delete()`, added in [28835]
* Documents a global in `is_customize_preview()`, added in [28999]
* phpDoc tweaks, adds an access modifier for `wpdb::esc_like()`, added in [28711]

See #28885.

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


git-svn-id: http://core.svn.wordpress.org/trunk@28947 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/comment-template.php

@@ -1940,6 +1940,8 @@ function wp_list_comments( $args = array(), $comments = null ) {
 	 *
 	 * @since 4.0.0
 	 *
+	 * @see wp_list_comments()
+	 *
 	 * @param array $r An array of arguments for displaying comments.
 	 */
 	$r = apply_filters( 'wp_list_comments_args', $r );

wp-includes/formatting.php

@@ -40,16 +40,18 @@ function wptexturize($text, $reset = false) {
 	// Set up static variables. Run once only.
 	if ( $reset || ! isset( $static_characters ) ) {
 		/**
-		 * Filter whether to skip running `wptexturize()`.
+		 * Filter whether to skip running wptexturize().
 		 *
-		 * Passing false to the filter will effectively short-circuit `wptexturize()`.
+		 * Passing false to the filter will effectively short-circuit wptexturize().
 		 * returning the original text passed to the function instead.
 		 *
-		 * The filter runs only once, the first time `wptexturize()` is called.
+		 * The filter runs only once, the first time wptexturize() is called.
 		 *
 		 * @since 4.0.0
 		 *
-		 * @param bool $run_texturize Whether to short-circuit `wptexturize()`.
+		 * @see wptexturize()
+		 *
+		 * @param bool $run_texturize Whether to short-circuit wptexturize().
 		 */
 		$run_texturize = apply_filters( 'run_wptexturize', $run_texturize );
 		if ( false === $run_texturize ) {

wp-includes/functions.php

@@ -3506,8 +3506,9 @@ function is_ssl() {
  *
  * @since 4.0.0
  * 
- * @param  string  $url The URL
+ * @param string $url The URL.
- * @return bool True if the given URL uses https, false if not (or if the URL is not valid).
+ * @return bool True if the given URL uses https, false if not (or if the URL
+ *              is not valid).
  */
 function is_https_url( $url ) {
 	return ( 'https' === parse_url( $url, PHP_URL_SCHEME ) );

wp-includes/l10n.php

@@ -821,6 +821,10 @@ function wp_get_pomo_file_data( $po_file ) {
  * Language selector. More to come.
  *
  * @since 4.0.0
+ *
+ * @see get_available_languages()
+ *
+ * @param array $args Optional arguments. Default empty array.
  */
 function wp_dropdown_languages( $args = array() ) {
 	if ( isset( $args['languages'] ) ) {

wp-includes/ms-blogs.php

@@ -910,7 +910,7 @@ function _update_blog_date_on_post_delete( $post_id ) {
  *
  * @since 4.0
  *
- * @param int $post_id Post ID
+ * @param int $post_id Post ID.
  */
 function _update_posts_count_on_delete( $post_id ) {
 	if ( 'publish' !== get_post_field( 'post_status', $post_id ) ) {

wp-includes/theme.php

@@ -1947,6 +1947,8 @@ function wp_customize_support_script() {
  *
  * @since 4.0.0
  *
+ * @global WP_Customize_Manager $wp_customize Customizer instance.
+ *
  * @return bool True if the site is being previewed in the Customizer, false otherwise.
  */
 function is_customize_preview() {

wp-includes/wp-db.php

@@ -1188,11 +1188,14 @@ class wpdb {
 	 *  $sql  = esc_sql( $wpdb->esc_like( $input ) );
 	 *
 	 * @since 4.0.0
+	 * @access public
 	 *
-	 * @param string $text The raw text to be escaped. The input typed by the user should have no extra or deleted slashes.
+	 * @param string $text The raw text to be escaped. The input typed by the user should have no
-	 * @return string Text in the form of a LIKE phrase. The output is not SQL safe. Call prepare or real_escape next.
+	 *                     extra or deleted slashes.
+	 * @return string Text in the form of a LIKE phrase. The output is not SQL safe. Call $wpdb::prepare()
+	 *                or real_escape next.
 	 */
-	function esc_like( $text ) {
+	public function esc_like( $text ) {
 		return addcslashes( $text, '_%\\' );
 	}