From 3724252959629559861ccdb46db0944f113eaaa1 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Tue, 3 Jun 2014 04:44:16 +0000 Subject: [PATCH] Ensure `$post_id` is documented as optional where applicable. See #28388. Built from https://develop.svn.wordpress.org/trunk@28654 git-svn-id: http://core.svn.wordpress.org/trunk@28472 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/comment-template.php | 2 +- wp-includes/comment.php | 4 +-- wp-includes/link-template.php | 2 +- wp-includes/post-template.php | 2 +- wp-includes/post.php | 53 ++++++++++++++++---------------- wp-includes/revision.php | 2 +- 6 files changed, 33 insertions(+), 32 deletions(-) diff --git a/wp-includes/comment-template.php b/wp-includes/comment-template.php index 3e88fe52dd..ae038a7734 100644 --- a/wp-includes/comment-template.php +++ b/wp-includes/comment-template.php @@ -641,7 +641,7 @@ function get_comment_link( $comment = null, $args = array() ) { * * @since 1.5.0 * - * @param int|WP_Post $post_id Post ID or WP_Post object. Default current post. + * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default is global `$post`. * @return string The link to the comments. */ function get_comments_link( $post_id = 0 ) { diff --git a/wp-includes/comment.php b/wp-includes/comment.php index c7d03f685a..eb0e5335dd 100644 --- a/wp-includes/comment.php +++ b/wp-includes/comment.php @@ -2195,10 +2195,10 @@ function do_trackbacks($post_id) { * * @since 1.2.0 * - * @param int $post_id Post ID. Not actually used. + * @param int $post_id Post ID. * @return int Same as Post ID from parameter */ -function generic_ping($post_id = 0) { +function generic_ping( $post_id = 0 ) { $services = get_option('ping_sites'); $services = explode("\n", $services); diff --git a/wp-includes/link-template.php b/wp-includes/link-template.php index 26b6f53e34..739d6bb511 100644 --- a/wp-includes/link-template.php +++ b/wp-includes/link-template.php @@ -290,7 +290,7 @@ function get_post_permalink( $id = 0, $leavename = false, $sample = false ) { * * @since 1.0.0 * - * @param int $post_id Optional. Post ID. + * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default is global `$post`. * @param mixed $deprecated Not used. * @return string */ diff --git a/wp-includes/post-template.php b/wp-includes/post-template.php index 60dd108206..60d09c7660 100644 --- a/wp-includes/post-template.php +++ b/wp-includes/post-template.php @@ -1719,7 +1719,7 @@ function wp_post_revision_title_expanded( $revision, $link = true ) { * @uses get_edit_post_link() * @uses get_the_author_meta() * - * @param int|WP_Post $post_id Optional. Post ID or post object. + * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default is global `$post`. * @param string $type 'all' (default), 'revision' or 'autosave' * @return null */ diff --git a/wp-includes/post.php b/wp-includes/post.php index 60e24f3823..afcad578c9 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -1857,8 +1857,8 @@ function delete_post_meta_by_key($post_meta_key) { * @since 1.2.0 * @link http://codex.wordpress.org/Function_Reference/get_post_custom * - * @param int $post_id Post ID. - * @return array + * @param int $post_id Optional. Post ID. Default is ID of the global `$post`. + * @return array Post meta for the given post. */ function get_post_custom( $post_id = 0 ) { $post_id = absint( $post_id ); @@ -1876,7 +1876,7 @@ function get_post_custom( $post_id = 0 ) { * @since 1.2.0 * @link http://codex.wordpress.org/Function_Reference/get_post_custom_keys * - * @param int $post_id post ID + * @param int $post_id Optional. Post ID. Default is ID of the global `$post`. * @return array|null Either array of the keys, or null if keys could not be retrieved. */ function get_post_custom_keys( $post_id = 0 ) { @@ -1899,7 +1899,7 @@ function get_post_custom_keys( $post_id = 0 ) { * @link http://codex.wordpress.org/Function_Reference/get_post_custom_values * * @param string $key Meta field key. - * @param int $post_id Post ID + * @param int $post_id Optional. Post ID. Default is ID of the global `$post`. * @return array Meta field values. */ function get_post_custom_values( $key = '', $post_id = 0 ) { @@ -1919,7 +1919,7 @@ function get_post_custom_values( $key = '', $post_id = 0 ) { * * @since 2.7.0 * - * @param int $post_id Optional. Post ID. + * @param int $post_id Optional. Post ID. Default is ID of the global `$post`. * @return bool Whether post is sticky. */ function is_sticky( $post_id = 0 ) { @@ -2565,8 +2565,9 @@ add_action( 'wp_trash_post', '_reset_front_page_settings_for_post' ); * * @uses wp_delete_post() if trash is disabled * - * @param int $post_id Post ID. - * @return mixed False on failure + * @param int $post_id Optional. Post ID. Default is ID of the global `$post` + * if EMPTY_TRASH_DAYS equals true. + * @return bool|array Post data array, otherwise false. */ function wp_trash_post($post_id = 0) { if ( !EMPTY_TRASH_DAYS ) @@ -2612,10 +2613,10 @@ function wp_trash_post($post_id = 0) { * * @since 2.9.0 * - * @param int $post_id Post ID. + * @param int $post_id Optional. Post ID. Default is ID of the global `$post`. * @return mixed False on failure */ -function wp_untrash_post($post_id = 0) { +function wp_untrash_post( $post_id = 0 ) { if ( !$post = get_post($post_id, ARRAY_A) ) return $post; @@ -2776,7 +2777,7 @@ function wp_untrash_post_comments($post = null) { * * @uses wp_get_object_terms() Retrieves the categories. Args details can be found here. * - * @param int $post_id Optional. The Post ID. + * @param int $post_id Optional. The Post ID. Does not default to the global `$post`. * @param array $args Optional. Overwrite the defaults. * @return array */ @@ -2801,7 +2802,7 @@ function wp_get_post_categories( $post_id = 0, $args = array() ) { * * @uses wp_get_object_terms() Gets the tags for returning. Args can be found here * - * @param int $post_id Optional. The Post ID + * @param int $post_id Optional. The Post ID. Does not default to the global `$post`. * @param array $args Optional. Overwrite the defaults * @return array List of post tags. */ @@ -2820,9 +2821,9 @@ function wp_get_post_tags( $post_id = 0, $args = array() ) { * * @uses wp_get_object_terms() Gets the tags for returning. Args can be found here * - * @param int $post_id Optional. The Post ID + * @param int $post_id Optional. The Post ID. Does not default to the global `$post`. * @param string $taxonomy The taxonomy for which to retrieve terms. Defaults to post_tag. - * @param array $args Optional. Overwrite the defaults + * @param array $args Optional. {@link wp_get_object_terms()} arguments. * @return array List of post tags. */ function wp_get_post_terms( $post_id = 0, $taxonomy = 'post_tag', $args = array() ) { @@ -3578,11 +3579,11 @@ function _truncate_post_slug( $slug, $length = 200 ) { * * @since 2.3.0 * - * @param int $post_id Post ID + * @param int $post_id Optional. The Post ID. Does not default to the global `$post`. * @param string $tags The tags to set for the post, separated by commas. * @return bool|null Will return false if $post_id is not an integer or is 0. Will return null otherwise */ -function wp_add_post_tags($post_id = 0, $tags = '') { +function wp_add_post_tags( $post_id = 0, $tags = '' ) { return wp_set_post_tags($post_id, $tags, true); } @@ -3592,7 +3593,7 @@ function wp_add_post_tags($post_id = 0, $tags = '') { * @since 2.3.0 * @uses wp_set_object_terms() Sets the tags for the post. * - * @param int $post_id Post ID. + * @param int $post_id Optional. The Post ID. Does not default to the global `$post`. * @param string $tags The tags to set for the post, separated by commas. * @param bool $append If true, don't delete existing tags, just add on. If false, replace the tags with the new tags. * @return mixed Array of affected term IDs. WP_Error or false on failure. @@ -3607,10 +3608,10 @@ function wp_set_post_tags( $post_id = 0, $tags = '', $append = false ) { * @since 2.8.0 * @uses wp_set_object_terms() Sets the tags for the post. * - * @param int $post_id Post ID. - * @param string $tags The tags to set for the post, separated by commas. + * @param int $post_id Optional. The Post ID. Does not default to the global `$post`. + * @param string $tags The tags to set for the post, separated by commas. * @param string $taxonomy Taxonomy name. Defaults to 'post_tag'. - * @param bool $append If true, don't delete existing tags, just add on. If false, replace the tags with the new tags. + * @param bool $append If true, don't delete existing tags, just add on. If false, replace the tags with the new tags. * @return mixed Array of affected term IDs. WP_Error or false on failure. */ function wp_set_post_terms( $post_id = 0, $tags = '', $taxonomy = 'post_tag', $append = false ) { @@ -3646,7 +3647,7 @@ function wp_set_post_terms( $post_id = 0, $tags = '', $taxonomy = 'post_tag', $a * * @since 2.1.0 * - * @param int $post_ID Post ID. + * @param int $post_ID Optional. The Post ID. Does not default to the global `$post`. * @param array|int $post_categories Optional. List of categories or ID of category. * @param bool $append If true, don't delete existing categories, just add on. If false, replace the categories with the new categories. * @return bool|mixed @@ -4834,7 +4835,7 @@ function wp_delete_attachment( $post_id, $force_delete = false ) { * * @since 2.1.0 * - * @param int $post_id Attachment ID + * @param int $post_id Attachment ID. Default 0. * @param bool $unfiltered Optional, default is false. If true, filters are not run. * @return string|bool Attachment meta field. False on failure. */ @@ -4893,7 +4894,7 @@ function wp_update_attachment_metadata( $post_id, $data ) { * * @since 2.1.0 * - * @param int $post_id Attachment ID. + * @param int $post_id Optional. Attachment ID. Default 0. * @return string */ function wp_get_attachment_url( $post_id = 0 ) { @@ -4940,7 +4941,7 @@ function wp_get_attachment_url( $post_id = 0 ) { * * @since 2.1.0 * - * @param int $post_id Attachment ID. + * @param int $post_id Optional. Attachment ID. Default 0. * @return mixed False on failure. Thumbnail file path on success. */ function wp_get_attachment_thumb_file( $post_id = 0 ) { @@ -4971,7 +4972,7 @@ function wp_get_attachment_thumb_file( $post_id = 0 ) { * * @since 2.1.0 * - * @param int $post_id Attachment ID + * @param int $post_id Optional. Attachment ID. Default 0. * @return string|bool False on failure. Thumbnail URL on success. */ function wp_get_attachment_thumb_url( $post_id = 0 ) { @@ -5006,8 +5007,8 @@ function wp_get_attachment_thumb_url( $post_id = 0 ) { * * @since 2.1.0 * - * @param int $post_id Attachment ID - * @return bool + * @param int $post_id Optional. Attachment ID. Default 0. + * @return bool Whether the attachment is an image. */ function wp_attachment_is_image( $post_id = 0 ) { $post_id = (int) $post_id; diff --git a/wp-includes/revision.php b/wp-includes/revision.php index ee02ce97fe..6aa7f6aaaa 100644 --- a/wp-includes/revision.php +++ b/wp-includes/revision.php @@ -409,7 +409,7 @@ function wp_delete_post_revision( $revision_id ) { * * @uses get_children() * - * @param int|object $post_id Post ID or post object + * @param int|WP_Post $post_id Optional. Post ID or WP_Post object. Default is global `$post`. * @return array An array of revisions, or an empty array if none. */ function wp_get_post_revisions( $post_id = 0, $args = null ) {