Docs: Clarify the purpose of post date/time functions.

This changeset clarifies the purpose of these functions and make the documentation more accurate and flexible. Instead of referring to the "date the post was written," the functions and filter descriptions now refer to the "date of the post." This change accommodates scenarios where the displayed date might not strictly correspond to the writing date (e.g. scheduled posts, backdated posts, or content where the "date" represents something other than creation).

Props casiepa, audrasjb, SergeyBiryukov, Rarst, helen, azouamauriac, pbearne.
Fixes #51289.




git-svn-id: https://develop.svn.wordpress.org/trunk@59691 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/general-template.php

@@ -2517,7 +2517,7 @@ function the_date_xml() {
 }
 
 /**
- * Displays or retrieves the date the current post was written (once per date)
+ * Displays or retrieves the date of the post (once per date).
  *
  * Will only output the date if the current post's date is different from the
  * previous one output.
@@ -2550,7 +2550,7 @@ function the_date( $format = '', $before = '', $after = '', $display = true ) {
 	}
 
 	/**
-	 * Filters the date a post was published for display.
+	 * Filters the date of the post, for display.
 	 *
 	 * @since 0.71
 	 *
@@ -2569,7 +2569,7 @@ function the_date( $format = '', $before = '', $after = '', $display = true ) {
 }
 
 /**
- * Retrieves the date on which the post was written.
+ * Retrieves the date of the post.
  *
  * Unlike the_date() this function will always return the date.
  * Modify output with the {@see 'get_the_date'} filter.
@@ -2592,7 +2592,7 @@ function get_the_date( $format = '', $post = null ) {
 	$the_date = get_post_time( $_format, false, $post, true );
 
 	/**
-	 * Filters the date a post was published.
+	 * Filters the date of the post.
 	 *
 	 * @since 3.0.0
 	 *
@@ -2618,7 +2618,7 @@ function the_modified_date( $format = '', $before = '', $after = '', $display =
 	$the_modified_date = $before . get_the_modified_date( $format ) . $after;
 
 	/**
-	 * Filters the date a post was last modified for display.
+	 * Filters the date a post was last modified, for display.
 	 *
 	 * @since 2.1.0
 	 *
@@ -2672,7 +2672,7 @@ function get_the_modified_date( $format = '', $post = null ) {
 }
 
 /**
- * Displays the time at which the post was written.
+ * Displays the date of the post.
  *
  * @since 0.71
  *
@@ -2682,7 +2682,7 @@ function get_the_modified_date( $format = '', $post = null ) {
  */
 function the_time( $format = '' ) {
 	/**
-	 * Filters the time a post was written for display.
+	 * Filters the date of the post, for display.
 	 *
 	 * @since 0.71
 	 *
@@ -2694,7 +2694,7 @@ function the_time( $format = '' ) {
 }
 
 /**
- * Retrieves the time at which the post was written.
+ * Retrieves the date of the post.
  *
  * @since 1.5.0
  *
@@ -2717,7 +2717,7 @@ function get_the_time( $format = '', $post = null ) {
 	$the_time = get_post_time( $_format, false, $post, true );
 
 	/**
-	 * Filters the time a post was written.
+	 * Filters the date of the post.
 	 *
 	 * @since 1.5.0
 	 *
@@ -2730,7 +2730,7 @@ function get_the_time( $format = '', $post = null ) {
 }
 
 /**
- * Retrieves the time at which the post was written.
+ * Retrieves the localized date of the post.
  *
  * @since 2.0.0
  *
@@ -2774,12 +2774,12 @@ function get_post_time( $format = 'U', $gmt = false, $post = null, $translate =
 	}
 
 	/**
-	 * Filters the localized time a post was written.
+	 * Filters the localized date of the post.
 	 *
 	 * @since 2.6.0
 	 *
 	 * @param string|int $time   Formatted date string or Unix timestamp if `$format` is 'U' or 'G'.
-	 * @param string     $format Format to use for retrieving the time the post was written.
+	 * @param string     $format Format to use for retrieving the date of the post.
 	 *                           Accepts 'G', 'U', or PHP date format.
 	 * @param bool       $gmt    Whether to retrieve the GMT time.
 	 */
@@ -2976,7 +2976,7 @@ function get_post_modified_time( $format = 'U', $gmt = false, $post = null, $tra
 }
 
 /**
- * Displays the weekday on which the post was written.
+ * Displays the weekday for the post.
  *
  * @since 0.71
  *
@@ -2994,7 +2994,7 @@ function the_weekday() {
 	$the_weekday = $wp_locale->get_weekday( get_post_time( 'w', false, $post ) );
 
 	/**
-	 * Filters the weekday on which the post was written, for display.
+	 * Filters the weekday of the post, for display.
 	 *
 	 * @since 0.71
 	 *
@@ -3004,7 +3004,7 @@ function the_weekday() {
 }
 
 /**
- * Displays the weekday on which the post was written.
+ * Displays the localized weekday date for the post
  *
  * Will only output the weekday if the current post's weekday is different from
  * the previous one output.
@@ -3037,7 +3037,7 @@ function the_weekday_date( $before = '', $after = '' ) {
 	}
 
 	/**
-	 * Filters the localized date on which the post was written, for display.
+	 * Filters the localized weekday date of the post, for display.
 	 *
 	 * @since 0.71
 	 *
@@ -4351,7 +4351,7 @@ function get_search_query( $escaped = true ) {
  */
 function the_search_query() {
 	/**
-	 * Filters the contents of the search query variable for display.
+	 * Filters the contents of the search query variable, for display.
 	 *
 	 * @since 2.3.0
 	 *
@@ -4984,7 +4984,7 @@ function wp_generator() {
  */
 function the_generator( $type ) {
 	/**
-	 * Filters the output of the XHTML generator tag for display.
+	 * Filters the output of the XHTML generator tag, for display.
 	 *
 	 * @since 2.5.0
 	 *