Docs: Add missing null to $post parameter types in various functions.

Props apermo.
Fixes #64645.

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

Author: SergeyBiryukov

src/wp-includes/category-template.php

@@ -1487,7 +1487,7 @@ function the_terms( $post_id, $taxonomy, $before = '', $sep = ', ', $after = ''
  *
  * @param string|int|array $category Optional. The category name/term_id/slug,
  *                                   or an array of them to check for. Default empty.
- * @param int|WP_Post      $post     Optional. Post to check. Defaults to the current post.
+ * @param int|WP_Post|null $post     Optional. Post to check. Defaults to the current post.
  * @return bool True if the current post has any of the given categories
  *              (or any category, if no category specified). False otherwise.
  */
@@ -1514,7 +1514,7 @@ function has_category( $category = '', $post = null ) {
  *
  * @param string|int|array $tag  Optional. The tag name/term_id/slug,
  *                               or an array of them to check for. Default empty.
- * @param int|WP_Post      $post Optional. Post to check. Defaults to the current post.
+ * @param int|WP_Post|null $post Optional. Post to check. Defaults to the current post.
  * @return bool True if the current post has any of the given tags
  *              (or any tag, if no tag specified). False otherwise.
  */
@@ -1535,7 +1535,7 @@ function has_tag( $tag = '', $post = null ) {
  * @param string|int|array $term     Optional. The term name/term_id/slug,
  *                                   or an array of them to check for. Default empty.
  * @param string           $taxonomy Optional. Taxonomy name. Default empty.
- * @param int|WP_Post      $post     Optional. Post to check. Defaults to the current post.
+ * @param int|WP_Post|null $post     Optional. Post to check. Defaults to the current post.
  * @return bool True if the current post has any of the given terms
  *              (or any term, if no term specified). False otherwise.
  */

src/wp-includes/comment-template.php

@@ -2157,8 +2157,8 @@ function comment_form_title( $no_reply_text = false, $reply_text = false, $link_
  *
  * @access private
  *
- * @param int|WP_Post $post The post the comment is being displayed for.
- *                          Defaults to the current global post.
+ * @param int|WP_Post|null $post The post the comment is being displayed for.
+ *                               Defaults to the current global post.
  * @return int Comment's reply to ID.
  */
 function _get_comment_reply_id( $post = null ) {

src/wp-includes/embed.php

@@ -413,7 +413,7 @@ function wp_maybe_enqueue_oembed_host_js( $html ) {
  *
  * @since 4.4.0
  *
- * @param int|WP_Post $post Optional. Post ID or object. Defaults to the current post.
+ * @param int|WP_Post|null $post Optional. Post ID or object. Defaults to the current post.
  * @return string|false The post embed URL on success, false if the post doesn't exist.
  */
 function get_post_embed_url( $post = null ) {
@@ -482,9 +482,9 @@ function get_oembed_endpoint_url( $permalink = '', $format = 'json' ) {
  *
  * @since 4.4.0
  *
- * @param int         $width  The width for the response.
- * @param int         $height The height for the response.
- * @param int|WP_Post $post   Optional. Post ID or object. Default is global `$post`.
+ * @param int              $width  The width for the response.
+ * @param int              $height The height for the response.
+ * @param int|WP_Post|null $post   Optional. Post ID or object. Default is global `$post`.
  * @return string|false Embed code on success, false if post doesn't exist.
  */
 function get_post_embed_html( $width, $height, $post = null ) {

src/wp-includes/general-template.php

@@ -2716,8 +2716,8 @@ function the_date( $format = '', $before = '', $after = '', $display = true ) {
  *
  * @since 3.0.0
  *
- * @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.
+ * @param string           $format Optional. PHP date format. Defaults to the 'date_format' option.
+ * @param int|WP_Post|null $post   Optional. Post ID or WP_Post object. Default current post.
  * @return string|int|false Date the current post was written. False on failure.
  */
 function get_the_date( $format = '', $post = null ) {
@@ -2782,8 +2782,8 @@ function the_modified_date( $format = '', $before = '', $after = '', $display =
  * @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.
- * @param int|WP_Post $post   Optional. Post ID or WP_Post object. Default current post.
+ * @param string           $format Optional. PHP date format. Defaults to the 'date_format' option.
+ * @param int|WP_Post|null $post   Optional. Post ID or WP_Post object. Default current post.
  * @return string|int|false Date the current post was modified. False on failure.
  */
 function get_the_modified_date( $format = '', $post = null ) {
@@ -2838,10 +2838,10 @@ function the_time( $format = '' ) {
  *
  * @since 1.5.0
  *
- * @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.
- * @param int|WP_Post $post   Post ID or post object. Default is global `$post` object.
+ * @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.
+ * @param int|WP_Post|null $post   Post ID or post object. Default is global `$post` object.
  * @return string|int|false Formatted date string or Unix timestamp if `$format` is 'U' or 'G'.
  *                          False on failure.
  */
@@ -2874,11 +2874,11 @@ 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. 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      Post ID or post object. Default is global `$post` object.
- * @param bool        $translate Whether to translate the time string. Default false.
+ * @param string           $format    Optional. Format to use for retrieving the time the post
+ *                                    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|null $post      Post ID or post object. Default is global `$post` object.
+ * @param bool             $translate Whether to translate the time string. Default false.
  * @return string|int|false Formatted date string or Unix timestamp if `$format` is 'U' or 'G'.
  *                          False on failure.
  */
@@ -2938,11 +2938,11 @@ function get_post_time( $format = 'U', $gmt = false, $post = null, $translate =
  *
  * @since 5.3.0
  *
- * @param int|WP_Post $post   Optional. Post ID or post object. Default is global `$post` object.
- * @param string      $field  Optional. Published or modified time to use from database. Accepts 'date' or 'modified'.
- *                            Default 'date'.
- * @param string      $source Optional. Local or UTC time to use from database. Accepts 'local' or 'gmt'.
- *                            Default 'local'.
+ * @param int|WP_Post|null $post   Optional. Post ID or post object. Default is global `$post` object.
+ * @param string           $field  Optional. Published or modified time to use from database. Accepts 'date' or 'modified'.
+ *                                 Default 'date'.
+ * @param string           $source Optional. Local or UTC time to use from database. Accepts 'local' or 'gmt'.
+ *                                 Default 'local'.
  * @return DateTimeImmutable|false Time object on success, false on failure.
  */
 function get_post_datetime( $post = null, $field = 'date', $source = 'local' ) {
@@ -2983,9 +2983,9 @@ function get_post_datetime( $post = null, $field = 'date', $source = 'local' ) {
  *
  * @since 5.3.0
  *
- * @param int|WP_Post $post  Optional. Post ID or post object. Default is global `$post` object.
- * @param string      $field Optional. Published or modified time to use from database. Accepts 'date' or 'modified'.
- *                           Default 'date'.
+ * @param int|WP_Post|null $post  Optional. Post ID or post object. Default is global `$post` object.
+ * @param string           $field Optional. Published or modified time to use from database. Accepts 'date' or 'modified'.
+ *                                Default 'date'.
  * @return int|false Unix timestamp on success, false on failure.
  */
 function get_post_timestamp( $post = null, $field = 'date' ) {
@@ -3026,10 +3026,10 @@ function the_modified_time( $format = '' ) {
  * @since 2.0.0
  * @since 4.6.0 Added the `$post` parameter.
  *
- * @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.
- * @param int|WP_Post $post   Optional. Post ID or WP_Post object. Default current post.
+ * @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.
+ * @param int|WP_Post|null $post   Optional. Post ID or WP_Post object. Default current post.
  * @return string|int|false Formatted date string or Unix timestamp. False on failure.
  */
 function get_the_modified_time( $format = '', $post = null ) {
@@ -3063,11 +3063,11 @@ 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. 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      Post ID or post object. Default is global `$post` object.
- * @param bool        $translate Whether to translate the time string. Default false.
+ * @param string           $format    Optional. Format to use for retrieving the time the post
+ *                                    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|null $post      Post ID or post object. Default is global `$post` object.
+ * @param bool             $translate Whether to translate the time string. Default false.
  * @return string|int|false Formatted date string or Unix timestamp if `$format` is 'U' or 'G'.
  *                          False on failure.
  */

src/wp-includes/link-template.php

@@ -94,7 +94,7 @@ function permalink_anchor( $mode = 'id' ) {
  *
  * @since 5.7.0
  *
- * @param WP_Post|int|null $post   Optional. Post ID or post object. Defaults to global $post.
+ * @param int|WP_Post|null $post   Optional. Post ID or post object. Defaults to global $post.
  * @param bool|null        $sample Optional. Whether to force consideration based on sample links.
  *                                 If omitted, a sample link is generated if a post object is passed
  *                                 with the filter property set to 'sample'.

src/wp-includes/ms-blogs.php

@@ -904,9 +904,9 @@ function _update_posts_count_on_delete( $post_id, $post ) {
  * @since 4.0.0
  * @since 4.9.0 Added the `$post` parameter.
  *
- * @param string  $new_status The status the post is changing to.
- * @param string  $old_status The status the post is changing from.
- * @param WP_Post $post       Post object
+ * @param string       $new_status The status the post is changing to.
+ * @param string       $old_status The status the post is changing from.
+ * @param WP_Post|null $post       Post object.
  */
 function _update_posts_count_on_transition_post_status( $new_status, $old_status, $post = null ) {
 	if ( $new_status === $old_status ) {

src/wp-includes/post-template.php

@@ -407,7 +407,7 @@ function the_excerpt() {
  * @since 0.71
  * @since 4.5.0 Introduced the `$post` parameter.
  *
- * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
+ * @param int|WP_Post|null $post Optional. Post ID or WP_Post object. Default is global $post.
  * @return string Post excerpt.
  */
 function get_the_excerpt( $post = null ) {
@@ -458,9 +458,9 @@ function has_excerpt( $post = 0 ) {
  *
  * @since 2.7.0
  *
- * @param string|string[] $css_class Optional. One or more classes to add to the class list.
- *                                   Default empty.
- * @param int|WP_Post     $post      Optional. Post ID or post object. Defaults to the global `$post`.
+ * @param string|string[]  $css_class Optional. One or more classes to add to the class list.
+ *                                    Default empty.
+ * @param int|WP_Post|null $post      Optional. Post ID or post object. Defaults to the global `$post`.
  */
 function post_class( $css_class = '', $post = null ) {
 	// Separates classes with a single space, collates classes for post DIV.
@@ -486,9 +486,9 @@ function post_class( $css_class = '', $post = null ) {
  * @since 2.7.0
  * @since 4.2.0 Custom taxonomy class names were added.
  *
- * @param string|string[] $css_class Optional. Space-separated string or array of class names
- *                                   to add to the class list. Default empty.
- * @param int|WP_Post     $post      Optional. Post ID or post object.
+ * @param string|string[]  $css_class Optional. Space-separated string or array of class names
+ *                                    to add to the class list. Default empty.
+ * @param int|WP_Post|null $post      Optional. Post ID or post object.
  * @return string[] Array of class names.
  */
 function get_post_class( $css_class = '', $post = null ) {
@@ -1883,7 +1883,7 @@ function is_page_template( $template = '' ) {
  * @since 3.4.0
  * @since 4.7.0 Now works with any post type, not just pages.
  *
- * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
+ * @param int|WP_Post|null $post Optional. Post ID or WP_Post object. Default is global $post.
  * @return string|false Page template filename. Returns an empty string when the default page template
  *                      is in use. Returns false if the post does not exist.
  */

src/wp-includes/post.php

@@ -1223,7 +1223,7 @@ function get_post_field( $field, $post = null, $context = 'display' ) {
  *
  * @since 2.0.0
  *
- * @param int|WP_Post $post Optional. Post ID or post object. Defaults to global $post.
+ * @param int|WP_Post|null $post Optional. Post ID or post object. Defaults to global $post.
  * @return string|false The mime type on success, false on failure.
  */
 function get_post_mime_type( $post = null ) {

src/wp-includes/widgets/class-wp-widget-media.php

@@ -360,8 +360,8 @@ class="media-widget-instance-property"
 	 *
 	 * @since 4.8.0
 	 *
-	 * @param array   $states An array of media states.
-	 * @param WP_Post $post   The current attachment object.
+	 * @param array        $states An array of media states.
+	 * @param WP_Post|null $post   The current attachment object.
 	 * @return array
 	 */
 	public function display_media_state( $states, $post = null ) {