From 396018ab34ba6dd9c8a12581cfe7ed8f5ebd63f7 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Tue, 19 Apr 2016 23:21:27 +0000 Subject: [PATCH] Docs: Properly notate optional parameters as such in a variety of DocBlocks in wp-includes/link-template.php. See #30406. Built from https://develop.svn.wordpress.org/trunk@37252 git-svn-id: http://core.svn.wordpress.org/trunk@37218 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/link-template.php | 121 ++++++++++++++++++---------------- wp-includes/version.php | 2 +- 2 files changed, 64 insertions(+), 59 deletions(-) diff --git a/wp-includes/link-template.php b/wp-includes/link-template.php index 40727bd076..a4d5a926bf 100644 --- a/wp-includes/link-template.php +++ b/wp-includes/link-template.php @@ -39,8 +39,9 @@ function the_permalink( $post = 0 ) { * * @global WP_Rewrite $wp_rewrite * - * @param string $string URL with or without a trailing slash. - * @param string $type_of_url The type of URL being considered (e.g. single, category, etc) for use in the filter. + * @param string $string URL with or without a trailing slash. + * @param string $type_of_url Optional. The type of URL being considered (e.g. single, category, etc) + * for use in the filter. Default empty string. * @return string The URL with the trailing slash appended or stripped. */ function user_trailingslashit($string, $type_of_url = '') { @@ -71,7 +72,7 @@ function user_trailingslashit($string, $type_of_url = '') { * * @since 0.71 * - * @param string $mode Permalink mode can be either 'title', 'id', or default, which is 'id'. + * @param string $mode Optional. Permalink mode. Accepts 'title' or 'id'. Default 'id'. */ function permalink_anchor( $mode = 'id' ) { $post = get_post(); @@ -242,9 +243,9 @@ function get_permalink( $post = 0, $leavename = false ) { * * @global WP_Rewrite $wp_rewrite * - * @param int $id Optional. Post ID. - * @param bool $leavename Optional, defaults to false. Whether to keep post name. - * @param bool $sample Optional, defaults to false. Is it a sample permalink. + * @param int $id Optional. Post ID. Default uses the global `$post`. + * @param bool $leavename Optional, defaults to false. Whether to keep post name. Default false. + * @param bool $sample Optional, defaults to false. Is it a sample permalink. Default false. * @return string|WP_Error The post permalink. */ function get_post_permalink( $id = 0, $leavename = false, $sample = false ) { @@ -300,9 +301,10 @@ function get_post_permalink( $id = 0, $leavename = false, $sample = false ) { * * @since 1.5.0 * - * @param int|object $post Optional. Post ID or object. - * @param bool $leavename Optional, defaults to false. Whether to keep page name. - * @param bool $sample Optional, defaults to false. Is it a sample permalink. + * @param int|WP_Post $post Optional. Post ID or object. Default uses the global `$post`. + * @param bool $leavename Optional. Whether to keep the page name. Default false. + * @param bool $sample Optional. Whether it should be treated as a sample permalink. + * Default false. * @return string The page permalink. */ function get_page_link( $post = false, $leavename = false, $sample = false ) { @@ -335,9 +337,10 @@ function get_page_link( $post = false, $leavename = false, $sample = false ) { * * @global WP_Rewrite $wp_rewrite * - * @param int|object $post Optional. Post ID or object. - * @param bool $leavename Optional. Leave name. - * @param bool $sample Optional. Sample permalink. + * @param int|WP_Post $post Optional. Post ID or object. Default uses the global `$post`. + * @param bool $leavename Optional. Whether to keep the page name. Default false. + * @param bool $sample Optional. Whether it should be treated as a sample permalink. + * Default false. * @return string The page permalink. */ function _get_page_link( $post = false, $leavename = false, $sample = false ) { @@ -380,8 +383,8 @@ function _get_page_link( $post = false, $leavename = false, $sample = false ) { * * @global WP_Rewrite $wp_rewrite * - * @param int|object $post Optional. Post ID or object. - * @param bool $leavename Optional. Leave name. + * @param int|object $post Optional. Post ID or object. Default uses the global `$post`. + * @param bool $leavename Optional. Whether to keep the page name. Default false. * @return string The attachment permalink. */ function get_attachment_link( $post = null, $leavename = false ) { @@ -439,7 +442,7 @@ function get_attachment_link( $post = null, $leavename = false ) { * @param int|bool $year False for current year or year for permalink. * @return string The permalink for the specified year archive. */ -function get_year_link($year) { +function get_year_link( $year ) { global $wp_rewrite; if ( !$year ) $year = gmdate('Y', current_time('timestamp')); @@ -550,7 +553,7 @@ function get_day_link($year, $month, $day) { * @since 3.0.0 * * @param string $anchor The link's anchor text. - * @param string $feed Optional, defaults to default feed. Feed type. + * @param string $feed Optional. Feed type. Default empty. */ function the_feed_link( $anchor, $feed = '' ) { $link = '' . $anchor . ''; @@ -574,10 +577,10 @@ function the_feed_link( $anchor, $feed = '' ) { * * @global WP_Rewrite $wp_rewrite * - * @param string $feed Optional, defaults to default feed. Feed type. + * @param string $feed Optional. Feed type. Default empty. * @return string The feed permalink. */ -function get_feed_link($feed = '') { +function get_feed_link( $feed = '' ) { global $wp_rewrite; $permalink = $wp_rewrite->get_feed_permastruct(); @@ -619,11 +622,11 @@ function get_feed_link($feed = '') { * * @since 2.2.0 * - * @param int $post_id Optional. Post ID. - * @param string $feed Optional. Feed type. + * @param int $post_id Optional. Post ID. Default is the ID of the global `$post`. + * @param string $feed Optional. Feed type. Default empty. * @return string The permalink for the comments feed for the given post. */ -function get_post_comments_feed_link($post_id = 0, $feed = '') { +function get_post_comments_feed_link( $post_id = 0, $feed = '' ) { $post_id = absint( $post_id ); if ( ! $post_id ) @@ -682,9 +685,9 @@ function get_post_comments_feed_link($post_id = 0, $feed = '') { * * @since 2.5.0 * - * @param string $link_text Descriptive text. - * @param int $post_id Optional post ID. Default to current post. - * @param string $feed Optional. Feed format. + * @param string $link_text Optional. Descriptive link text. Default 'Comments Feed'. + * @param int $post_id Optional. Post ID. Default is the ID of the global `$post`. + * @param string $feed Optional. Feed format. Default empty. */ function post_comments_feed_link( $link_text = '', $post_id = '', $feed = '' ) { $url = get_post_comments_feed_link( $post_id, $feed ); @@ -713,8 +716,8 @@ function post_comments_feed_link( $link_text = '', $post_id = '', $feed = '' ) { * * @since 2.5.0 * - * @param int $author_id ID of an author. - * @param string $feed Optional. Feed type. + * @param int $author_id Author ID. + * @param string $feed Optional. Feed type. Default empty. * @return string Link to the feed for the author specified by $author_id. */ function get_author_feed_link( $author_id, $feed = '' ) { @@ -757,8 +760,8 @@ function get_author_feed_link( $author_id, $feed = '' ) { * * @since 2.5.0 * - * @param int $cat_id ID of a category. - * @param string $feed Optional. Feed type. + * @param int $cat_id Category ID. + * @param string $feed Optional. Feed type. Default empty. * @return string Link to the feed for the category specified by $cat_id. */ function get_category_feed_link( $cat_id, $feed = '' ) { @@ -773,9 +776,9 @@ function get_category_feed_link( $cat_id, $feed = '' ) { * * @since 3.0.0 * - * @param int $term_id ID of a category. - * @param string $taxonomy Optional. Taxonomy of $term_id - * @param string $feed Optional. Feed type. + * @param int $term_id Term ID. + * @param string $taxonomy Optional. Taxonomy of `$term_id`. Default 'category'. + * @param string $feed Optional. Feed type. Default empty. * @return string|false Link to the feed for the term specified by $term_id and $taxonomy. */ function get_term_feed_link( $term_id, $taxonomy = 'category', $feed = '' ) { @@ -853,7 +856,7 @@ function get_term_feed_link( $term_id, $taxonomy = 'category', $feed = '' ) { * @since 2.3.0 * * @param int $tag_id Tag ID. - * @param string $feed Optional. Feed type. + * @param string $feed Optional. Feed type. Default empty. * @return string The feed permalink for the given tag. */ function get_tag_feed_link( $tag_id, $feed = '' ) { @@ -865,8 +868,8 @@ function get_tag_feed_link( $tag_id, $feed = '' ) { * * @since 2.7.0 * - * @param int $tag_id Tag ID - * @param string $taxonomy Taxonomy + * @param int $tag_id Tag ID. + * @param string $taxonomy Optional. Taxonomy slug. Default 'post_tag'. * @return string The edit tag link URL for the given tag. */ function get_edit_tag_link( $tag_id, $taxonomy = 'post_tag' ) { @@ -885,10 +888,11 @@ function get_edit_tag_link( $tag_id, $taxonomy = 'post_tag' ) { * * @since 2.7.0 * - * @param string $link Optional. Anchor text. - * @param string $before Optional. Display before edit link. - * @param string $after Optional. Display after edit link. - * @param object $tag Tag object. + * @param string $link Optional. Anchor text. Default empty. + * @param string $before Optional. Display before edit link. Default empty. + * @param string $after Optional. Display after edit link. Default empty. + * @param WP_Term $tag Optional. Term object. If null, the queried object will be inspected. + * Default null. */ function edit_tag_link( $link = '', $before = '', $after = '', $tag = null ) { $link = edit_term_link( $link, '', '', $tag, false ); @@ -910,9 +914,11 @@ function edit_tag_link( $link = '', $before = '', $after = '', $tag = null ) { * @since 4.5.0 The `$taxonomy` argument was made optional. * * @param int $term_id Term ID. - * @param string $taxonomy Optional. Taxonomy. Defaults to the taxonomy of the term identified by `$term_id`. - * @param string $object_type Optional. The object type. Used to highlight the proper post type menu on the linked page. - * Defaults to the first object_type associated with the taxonomy. + * @param string $taxonomy Optional. Taxonomy. Defaults to the taxonomy of the term identified + * by `$term_id`. + * @param string $object_type Optional. The object type. Used to highlight the proper post type + * menu on the linked page. Defaults to the first object_type associated + * with the taxonomy. * @return string|null The edit term link URL for the given term, or null on failure. */ function get_edit_term_link( $term_id, $taxonomy = '', $object_type = '' ) { @@ -1007,7 +1013,7 @@ function edit_term_link( $link = '', $before = '', $after = '', $term = null, $e * * @global WP_Rewrite $wp_rewrite * - * @param string $query Optional. The query string to use. If empty the current query is used. + * @param string $query Optional. The query string to use. If empty the current query is used. Default empty. * @return string The search permalink. */ function get_search_link( $query = '' ) { @@ -1047,8 +1053,8 @@ function get_search_link( $query = '' ) { * * @global WP_Rewrite $wp_rewrite * - * @param string $search_query Optional. Search query. - * @param string $feed Optional. Feed type. + * @param string $search_query Optional. Search query. Default empty. + * @param string $feed Optional. Feed type. Default empty. * @return string The search results feed permalink. */ function get_search_feed_link($search_query = '', $feed = '') { @@ -1086,8 +1092,8 @@ function get_search_feed_link($search_query = '', $feed = '') { * * @global WP_Rewrite $wp_rewrite * - * @param string $search_query Optional. Search query. - * @param string $feed Optional. Feed type. + * @param string $search_query Optional. Search query. Default empty. + * @param string $feed Optional. Feed type. Default empty. * @return string The comments feed search results permalink. */ function get_search_comments_feed_link($search_query = '', $feed = '') { @@ -1169,7 +1175,7 @@ function get_post_type_archive_link( $post_type ) { * @since 3.1.0 * * @param string $post_type Post type - * @param string $feed Optional. Feed type + * @param string $feed Optional. Feed type. Default empty. * @return string|false The post type feed permalink. */ function get_post_type_archive_feed_link( $post_type, $feed = '' ) { @@ -1208,9 +1214,11 @@ function get_post_type_archive_feed_link( $post_type, $feed = '' ) { * * @since 4.4.0 * - * @param int|WP_Post $post Optional. Post ID or `WP_Post` object. Defaults to global post. + * @param int|WP_Post $post Optional. Post ID or `WP_Post` object. Defaults to global `$post`. * @param array $query_args Optional. Array of additional query args to be appended to the link. - * @param string $preview_link Optional. Base preview link to be used if it should differ from the post permalink. + * Default empty array. + * @param string $preview_link Optional. Base preview link to be used if it should differ from the + * post permalink. Default empty. * @return string URL used for the post preview. */ function get_preview_post_link( $post = null, $query_args = array(), $preview_link = '' ) { @@ -1402,16 +1410,13 @@ function get_edit_comment_link( $comment_id = 0 ) { * Displays the edit comment link with formatting. * * @since 1.0.0 - * @since 4.6.0 The `$comment` and `$class` arguments were added. * - * @param string $text Optional. Anchor text. - * @param string $before Optional. Display before edit link. - * @param string $after Optional. Display after edit link. - * @param int|WP_Comment $comment Optional. Comment ID or WP_Comment object. - * @param string $class Optional. Add custom class to link. + * @param string $text Optional. Anchor text. + * @param string $before Optional. Display before edit link. + * @param string $after Optional. Display after edit link. */ -function edit_comment_link( $text = null, $before = '', $after = '', $comment = 0, $class = 'comment-edit-link' ) { - $comment = get_comment( $comment ); +function edit_comment_link( $text = null, $before = '', $after = '' ) { + $comment = get_comment(); if ( ! current_user_can( 'edit_comment', $comment->comment_ID ) ) { return; @@ -1421,7 +1426,7 @@ function edit_comment_link( $text = null, $before = '', $after = '', $comment = $text = __( 'Edit This' ); } - $link = '' . $text . ''; + $link = '' . $text . ''; /** * Filters the comment edit link anchor tag. diff --git a/wp-includes/version.php b/wp-includes/version.php index dd79457b07..dd5ae007b7 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -4,7 +4,7 @@ * * @global string $wp_version */ -$wp_version = '4.6-alpha-37251'; +$wp_version = '4.6-alpha-37252'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.