From 5f4a8f75b5fd529362dcd992f0da46ea88fb1826 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Tue, 1 Sep 2020 00:41:19 +0000 Subject: [PATCH] Docs: Synchronize the description of the `$format` parameter in various date/time functions for posts and comments. See #50768. git-svn-id: https://develop.svn.wordpress.org/trunk@48929 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/comment-template.php | 12 ++-- src/wp-includes/general-template.php | 84 +++++++++++++--------------- 2 files changed, 46 insertions(+), 50 deletions(-) diff --git a/src/wp-includes/comment-template.php b/src/wp-includes/comment-template.php index b7c644db1e..d3417db02b 100644 --- a/src/wp-includes/comment-template.php +++ b/src/wp-includes/comment-template.php @@ -544,7 +544,7 @@ function get_comment_class( $class = '', $comment_id = null, $post_id = null ) { * @since 1.5.0 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. * - * @param string $format Optional. The format of the date. Default user's setting. + * @param string $format Optional. PHP date format. Defaults to the 'date_format' option. * @param int|WP_Comment $comment_ID WP_Comment or ID of the comment for which to get the date. * Default current comment. * @return string The comment's date. @@ -562,7 +562,7 @@ function get_comment_date( $format = '', $comment_ID = 0 ) { * @since 1.5.0 * * @param string|int $date Formatted date string or Unix timestamp. - * @param string $format The format of the date. + * @param string $format PHP date format. * @param WP_Comment $comment The comment object. */ return apply_filters( 'get_comment_date', $date, $format, $comment ); @@ -574,7 +574,7 @@ function get_comment_date( $format = '', $comment_ID = 0 ) { * @since 0.71 * @since 4.4.0 Added the ability for `$comment_ID` to also accept a WP_Comment object. * - * @param string $format Optional. The format of the date. Default user's settings. + * @param string $format Optional. PHP date format. Defaults to the 'date_format' option. * @param int|WP_Comment $comment_ID WP_Comment or ID of the comment for which to print the date. * Default current comment. */ @@ -1033,7 +1033,7 @@ function comment_text( $comment_ID = 0, $args = array() ) { * * @since 1.5.0 * - * @param string $format Optional. The format of the time. Default user's settings. + * @param string $format Optional. PHP date format. Defaults to the 'time_format' option. * @param bool $gmt Optional. Whether to use the GMT date. Default false. * @param bool $translate Optional. Whether to translate the time (for use in feeds). * Default true. @@ -1054,7 +1054,7 @@ function get_comment_time( $format = '', $gmt = false, $translate = true ) { * @since 1.5.0 * * @param string|int $date The comment time, formatted as a date string or Unix timestamp. - * @param string $format Date format. + * @param string $format PHP date format. * @param bool $gmt Whether the GMT date is in use. * @param bool $translate Whether the time is translated. * @param WP_Comment $comment The comment object. @@ -1067,7 +1067,7 @@ function get_comment_time( $format = '', $gmt = false, $translate = true ) { * * @since 0.71 * - * @param string $format Optional. The format of the time. Default user's settings. + * @param string $format Optional. PHP date format. Defaults to the 'time_format' option. */ function comment_time( $format = '' ) { echo get_comment_time( $format ); diff --git a/src/wp-includes/general-template.php b/src/wp-includes/general-template.php index ec9eba3e93..01e7fa72d1 100644 --- a/src/wp-includes/general-template.php +++ b/src/wp-includes/general-template.php @@ -2470,9 +2470,9 @@ function the_date_xml() { * @global string $currentday The day of the current post in the loop. * @global string $previousday The day of the previous post in the loop. * - * @param string $format Optional. PHP date format defaults to the date_format option if not specified. - * @param string $before Optional. Output before the date. - * @param string $after Optional. Output after the date. + * @param string $format Optional. PHP date format. Defaults to the 'date_format' option. + * @param string $before Optional. Output before the date. Default empty. + * @param string $after Optional. Output after the date. Default empty. * @param bool $echo Optional. Whether to echo the date or return it. Default true. * @return string|void String if retrieving. */ @@ -2492,8 +2492,7 @@ function the_date( $format = '', $before = '', $after = '', $echo = true ) { * @since 0.71 * * @param string $the_date The formatted date string. - * @param string $format PHP date format. Defaults to 'date_format' option - * if not specified. + * @param string $format PHP date format. * @param string $before HTML output before the date. * @param string $after HTML output after the date. */ @@ -2514,7 +2513,7 @@ function the_date( $format = '', $before = '', $after = '', $echo = true ) { * * @since 3.0.0 * - * @param string $format Optional. PHP date format defaults to the date_format option if not specified. + * @param string $format Optional. PHP date format. Defaults to the 'date_format' option. * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default current post. * @return string|false Date the current post was written. False on failure. */ @@ -2535,8 +2534,7 @@ function get_the_date( $format = '', $post = null ) { * @since 3.0.0 * * @param string $the_date The formatted date. - * @param string $format PHP date format. Defaults to 'date_format' option - * if not specified. + * @param string $format PHP date format. * @param int|WP_Post $post The post object or ID. */ return apply_filters( 'get_the_date', $the_date, $format, $post ); @@ -2547,9 +2545,9 @@ function get_the_date( $format = '', $post = null ) { * * @since 2.1.0 * - * @param string $format Optional. PHP date format defaults to the date_format option if not specified. - * @param string $before Optional. Output before the date. - * @param string $after Optional. Output after the date. + * @param string $format Optional. PHP date format. Defaults to the 'date_format' option. + * @param string $before Optional. Output before the date. Default empty. + * @param string $after Optional. Output after the date. Default empty. * @param bool $echo Optional. Whether to echo the date or return it. Default true. * @return string|void String if retrieving. */ @@ -2561,11 +2559,10 @@ function the_modified_date( $format = '', $before = '', $after = '', $echo = tru * * @since 2.1.0 * - * @param string $the_modified_date The last modified date. - * @param string $format PHP date format. Defaults to 'date_format' option - * if not specified. - * @param string $before HTML output before the date. - * @param string $after HTML output after the date. + * @param string|false $the_modified_date The last modified date or false if no post is found. + * @param string $format PHP date format. + * @param string $before HTML output before the date. + * @param string $after HTML output after the date. */ $the_modified_date = apply_filters( 'the_modified_date', $the_modified_date, $format, $before, $after ); @@ -2583,7 +2580,7 @@ function the_modified_date( $format = '', $before = '', $after = '', $echo = tru * @since 2.1.0 * @since 4.6.0 Added the `$post` parameter. * - * @param string $format Optional. PHP date format defaults to the date_format option if not specified. + * @param string $format Optional. PHP date format. Defaults to the 'date_format' option. * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default current post. * @return string|false Date the current post was modified. False on failure. */ @@ -2605,9 +2602,8 @@ function get_the_modified_date( $format = '', $post = null ) { * @since 2.1.0 * @since 4.6.0 Added the `$post` parameter. * - * @param string|bool $the_time The formatted date or false if no post is found. - * @param string $format PHP date format. Defaults to value specified in - * 'date_format' option. + * @param string|false $the_time The formatted date or false if no post is found. + * @param string $format PHP date format. * @param WP_Post|null $post WP_Post object or null if no post is found. */ return apply_filters( 'get_the_modified_date', $the_time, $format, $post ); @@ -2618,7 +2614,9 @@ function get_the_modified_date( $format = '', $post = null ) { * * @since 0.71 * - * @param string $format Either 'G', 'U', or PHP date format. + * @param string $format Optional. Format to use for retrieving the time the post + * was written. Accepts 'G', 'U', or PHP date format. + * Defaults to the 'time_format' option. */ function the_time( $format = '' ) { /** @@ -2627,8 +2625,8 @@ function the_time( $format = '' ) { * @since 0.71 * * @param string $get_the_time The formatted time. - * @param string $format The time format. Accepts 'G', 'U', - * or PHP date format. + * @param string $format Format to use for retrieving the time the post + * was written. Accepts 'G', 'U', or PHP date format. */ echo apply_filters( 'the_time', get_the_time( $format ), $format ); } @@ -2639,8 +2637,8 @@ function the_time( $format = '' ) { * @since 1.5.0 * * @param string $format Optional. Format to use for retrieving the time the post - * was written. Either 'G', 'U', or PHP date format defaults - * to the value specified in the time_format option. Default empty. + * was written. Accepts 'G', 'U', or PHP date format. + * Defaults to the 'time_format' option. * @param int|WP_Post $post WP_Post object or ID. Default is global `$post` object. * @return string|int|false Formatted date string or Unix timestamp if `$format` is 'U' or 'G'. * False on failure. @@ -2662,9 +2660,8 @@ function get_the_time( $format = '', $post = null ) { * @since 1.5.0 * * @param string $the_time The formatted time. - * @param string $format Format to use for retrieving the time the post was written. - * Accepts 'G', 'U', or PHP date format value specified - * in 'time_format' option. Default empty. + * @param string $format Format to use for retrieving the time the post + * was written. Accepts 'G', 'U', or PHP date format. * @param int|WP_Post $post WP_Post object or ID. */ return apply_filters( 'get_the_time', $the_time, $format, $post ); @@ -2676,7 +2673,7 @@ function get_the_time( $format = '', $post = null ) { * @since 2.0.0 * * @param string $format Optional. Format to use for retrieving the time the post - * was written. Either 'G', 'U', or PHP date format. Default 'U'. + * was written. Accepts 'G', 'U', or PHP date format. Default 'U'. * @param bool $gmt Optional. Whether to retrieve the GMT time. Default false. * @param int|WP_Post $post WP_Post object or ID. Default is global `$post` object. * @param bool $translate Whether to translate the time string. Default false. @@ -2804,8 +2801,9 @@ function get_post_timestamp( $post = null, $field = 'date' ) { * * @since 2.0.0 * - * @param string $format Optional. Either 'G', 'U', or PHP date format defaults - * to the value specified in the time_format option. + * @param string $format Optional. Format to use for retrieving the time the post + * was modified. Accepts 'G', 'U', or PHP date format. + * Defaults to the 'time_format' option. */ function the_modified_time( $format = '' ) { /** @@ -2813,10 +2811,9 @@ function the_modified_time( $format = '' ) { * * @since 2.0.0 * - * @param string $get_the_modified_time The formatted time. - * @param string $format The time format. Accepts 'G', 'U', - * or PHP date format. Defaults to value - * specified in 'time_format' option. + * @param string|false $get_the_modified_time The formatted time or false if no post is found. + * @param string $format Format to use for retrieving the time the post + * was modified. Accepts 'G', 'U', or PHP date format. */ echo apply_filters( 'the_modified_time', get_the_modified_time( $format ), $format ); } @@ -2828,8 +2825,8 @@ function the_modified_time( $format = '' ) { * @since 4.6.0 Added the `$post` parameter. * * @param string $format Optional. Format to use for retrieving the time the post - * was modified. Either 'G', 'U', or PHP date format defaults - * to the value specified in the time_format option. Default empty. + * was modified. Accepts 'G', 'U', or PHP date format. + * Defaults to the 'time_format' option. * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default current post. * @return string|false Formatted date string or Unix timestamp. False on failure. */ @@ -2851,10 +2848,9 @@ function get_the_modified_time( $format = '', $post = null ) { * @since 2.0.0 * @since 4.6.0 Added the `$post` parameter. * - * @param string|bool $the_time The formatted time or false if no post is found. - * @param string $format Format to use for retrieving the time the post was - * written. Accepts 'G', 'U', or PHP date format. Defaults - * to value specified in 'time_format' option. + * @param string|false $the_time The formatted time or false if no post is found. + * @param string $format Format to use for retrieving the time the post + * was modified. Accepts 'G', 'U', or PHP date format. * @param WP_Post|null $post WP_Post object or null if no post is found. */ return apply_filters( 'get_the_modified_time', $the_time, $format, $post ); @@ -2866,7 +2862,7 @@ function get_the_modified_time( $format = '', $post = null ) { * @since 2.0.0 * * @param string $format Optional. Format to use for retrieving the time the post - * was modified. Either 'G', 'U', or PHP date format. Default 'U'. + * was modified. Accepts 'G', 'U', or PHP date format. Default 'U'. * @param bool $gmt Optional. Whether to retrieve the GMT time. Default false. * @param int|WP_Post $post WP_Post object or ID. Default is global `$post` object. * @param bool $translate Whether to translate the time string. Default false. @@ -2957,8 +2953,8 @@ function the_weekday() { * @global string $currentday The day of the current post in the loop. * @global string $previousweekday The day of the previous post in the loop. * - * @param string $before Optional. Output before the date. - * @param string $after Optional. Output after the date. + * @param string $before Optional. Output before the date. Default empty. + * @param string $after Optional. Output after the date. Default empty. */ function the_weekday_date( $before = '', $after = '' ) { global $wp_locale, $currentday, $previousweekday;