From 29325967e1b304820b29eee68daa70ca5e864496 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Fri, 15 Apr 2016 16:57:15 +0000 Subject: [PATCH] Docs: Use third-person singular verbs in DocBlock and hook doc summaries in wp-includes/link-template.php. See #30406. git-svn-id: https://develop.svn.wordpress.org/trunk@37213 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/link-template.php | 329 +++++++++++++++--------------- 1 file changed, 162 insertions(+), 167 deletions(-) diff --git a/src/wp-includes/link-template.php b/src/wp-includes/link-template.php index 11c4e40022..ef5bfdc67d 100644 --- a/src/wp-includes/link-template.php +++ b/src/wp-includes/link-template.php @@ -7,7 +7,7 @@ */ /** - * Display the permalink for the current post. + * Displays the permalink for the current post. * * @since 1.2.0 * @since 4.4.0 Added the `$post` parameter. @@ -16,7 +16,7 @@ */ function the_permalink( $post = 0 ) { /** - * Filter the display of the permalink for the current post. + * Filters the display of the permalink for the current post. * * @since 1.5.0 * @since 4.4.0 Added the `$post` parameter. @@ -28,7 +28,7 @@ function the_permalink( $post = 0 ) { } /** - * Retrieve trailing slash string, if site is set for adding trailing slashes. + * Retrieves a trailing-slashed string if the site is set for adding trailing slashes. * * Conditionally adds a trailing slash if the permalink structure has a trailing * slash, strips the trailing slash if not. The string is passed through the @@ -36,6 +36,7 @@ function the_permalink( $post = 0 ) { * site is not set to have them. * * @since 2.2.0 + * * @global WP_Rewrite $wp_rewrite * * @param string $string URL with or without a trailing slash. @@ -50,8 +51,7 @@ function user_trailingslashit($string, $type_of_url = '') { $string = untrailingslashit($string); /** - * Filter the trailing slashed string, depending on whether the site is set - * to use training slashes. + * Filters the trailing-slashed string, depending on whether the site is set to use trailing slashes. * * @since 2.2.0 * @@ -64,7 +64,7 @@ function user_trailingslashit($string, $type_of_url = '') { } /** - * Display permalink anchor for current post. + * Displays the permalink anchor for the current post. * * The permalink mode title will use the post title for the 'a' element 'id' * attribute. The id mode uses 'post-' with the post ID for the 'id' attribute. @@ -88,7 +88,7 @@ function permalink_anchor( $mode = 'id' ) { } /** - * Retrieve full permalink for current post or post ID. + * Retrieves the full permalink for the current post or post ID. * * This function is an alias for get_permalink(). * @@ -106,7 +106,7 @@ function get_the_permalink( $post = 0, $leavename = false ) { } /** - * Retrieve full permalink for current post or post ID. + * Retrieves the full permalink for the current post or post ID. * * @since 1.0.0 * @@ -149,7 +149,7 @@ function get_permalink( $post = 0, $leavename = false ) { $permalink = get_option('permalink_structure'); /** - * Filter the permalink structure for a post before token replacement occurs. + * Filters the permalink structure for a post before token replacement occurs. * * Only applies to posts with post_type of 'post'. * @@ -222,7 +222,7 @@ function get_permalink( $post = 0, $leavename = false ) { } /** - * Filter the permalink for a post. + * Filters the permalink for a post. * * Only applies to posts with post_type of 'post'. * @@ -236,7 +236,7 @@ function get_permalink( $post = 0, $leavename = false ) { } /** - * Retrieve the permalink for a post with a custom post type. + * Retrieves the permalink for a post of a custom post type. * * @since 3.0.0 * @@ -281,7 +281,7 @@ function get_post_permalink( $id = 0, $leavename = false, $sample = false ) { } /** - * Filter the permalink for a post with a custom post type. + * Filters the permalink for a post of a custom post type. * * @since 3.0.0 * @@ -294,7 +294,7 @@ function get_post_permalink( $id = 0, $leavename = false, $sample = false ) { } /** - * Retrieve the permalink for current page or page ID. + * Retrieves the permalink for the current page or page ID. * * Respects page_on_front. Use this one. * @@ -326,7 +326,7 @@ function get_page_link( $post = false, $leavename = false, $sample = false ) { } /** - * Retrieve the page permalink. + * Retrieves the page permalink. * * Ignores page_on_front. Internal use only. * @@ -372,7 +372,7 @@ function _get_page_link( $post = false, $leavename = false, $sample = false ) { } /** - * Retrieve permalink for attachment. + * Retrieves the permalink for an attachment. * * This can be used in the WordPress Loop or outside of it. * @@ -419,7 +419,7 @@ function get_attachment_link( $post = null, $leavename = false ) { $link = home_url( '/?attachment_id=' . $post->ID ); /** - * Filter the permalink for an attachment. + * Filters the permalink for an attachment. * * @since 2.0.0 * @@ -430,7 +430,7 @@ function get_attachment_link( $post = null, $leavename = false ) { } /** - * Retrieve the permalink for the year archives. + * Retrieves the permalink for the year archives. * * @since 1.5.0 * @@ -452,7 +452,7 @@ function get_year_link($year) { } /** - * Filter the year archive permalink. + * Filters the year archive permalink. * * @since 1.5.0 * @@ -463,7 +463,7 @@ function get_year_link($year) { } /** - * Retrieve the permalink for the month archives with year. + * Retrieves the permalink for the month archives with year. * * @since 1.0.0 * @@ -489,7 +489,7 @@ function get_month_link($year, $month) { } /** - * Filter the month archive permalink. + * Filters the month archive permalink. * * @since 1.5.0 * @@ -501,7 +501,7 @@ function get_month_link($year, $month) { } /** - * Retrieve the permalink for the day archives with year and month. + * Retrieves the permalink for the day archives with year and month. * * @since 1.0.0 * @@ -545,7 +545,7 @@ function get_day_link($year, $month, $day) { } /** - * Display the permalink for the feed type. + * Displays the permalink for the feed type. * * @since 3.0.0 * @@ -556,7 +556,7 @@ function the_feed_link( $anchor, $feed = '' ) { $link = '' . $anchor . ''; /** - * Filter the feed link anchor tag. + * Filters the feed link anchor tag. * * @since 3.0.0 * @@ -568,7 +568,7 @@ function the_feed_link( $anchor, $feed = '' ) { } /** - * Retrieve the permalink for the feed type. + * Retrieves the permalink for the feed type. * * @since 1.5.0 * @@ -604,7 +604,7 @@ function get_feed_link($feed = '') { } /** - * Filter the feed type permalink. + * Filters the feed type permalink. * * @since 1.5.0 * @@ -615,7 +615,7 @@ function get_feed_link($feed = '') { } /** - * Retrieve the permalink for the post comments feed. + * Retrieves the permalink for the post comments feed. * * @since 2.2.0 * @@ -664,7 +664,7 @@ function get_post_comments_feed_link($post_id = 0, $feed = '') { } /** - * Filter the post comments feed permalink. + * Filters the post comments feed permalink. * * @since 1.5.1 * @@ -674,7 +674,7 @@ function get_post_comments_feed_link($post_id = 0, $feed = '') { } /** - * Display the comment feed link for a post. + * Displays the comment feed link for a post. * * Prints out the comment feed link for a post. Link text is placed in the * anchor. If no link text is specified, default text is used. If no post ID is @@ -694,7 +694,7 @@ function post_comments_feed_link( $link_text = '', $post_id = '', $feed = '' ) { $link = '' . $link_text . ''; /** - * Filter the post comment feed link anchor tag. + * Filters the post comment feed link anchor tag. * * @since 2.8.0 * @@ -706,7 +706,7 @@ function post_comments_feed_link( $link_text = '', $post_id = '', $feed = '' ) { } /** - * Retrieve the feed link for a given author. + * Retrieves the feed link for a given author. * * Returns a link to the feed for all posts by a given author. A specific feed * can be requested or left blank to get the default feed. @@ -737,7 +737,7 @@ function get_author_feed_link( $author_id, $feed = '' ) { } /** - * Filter the feed link for a given author. + * Filters the feed link for a given author. * * @since 1.5.1 * @@ -750,7 +750,7 @@ function get_author_feed_link( $author_id, $feed = '' ) { } /** - * Retrieve the feed link for a category. + * Retrieves the feed link for a category. * * Returns a link to the feed for all posts in a given category. A specific feed * can be requested or left blank to get the default feed. @@ -766,7 +766,7 @@ function get_category_feed_link( $cat_id, $feed = '' ) { } /** - * Retrieve the feed link for a term. + * Retrieves the feed link for a term. * * Returns a link to the feed for all posts in a given term. A specific feed * can be requested or left blank to get the default feed. @@ -848,7 +848,7 @@ function get_term_feed_link( $term_id, $taxonomy = 'category', $feed = '' ) { } /** - * Retrieve permalink for feed of tag. + * Retrieves the permalink for a tag feed. * * @since 2.3.0 * @@ -861,7 +861,7 @@ function get_tag_feed_link( $tag_id, $feed = '' ) { } /** - * Retrieve edit tag link. + * Retrieves the edit link for a tag. * * @since 2.7.0 * @@ -881,7 +881,7 @@ function get_edit_tag_link( $tag_id, $taxonomy = 'post_tag' ) { } /** - * Display or retrieve edit tag link with formatting. + * Displays or retrieves the edit link for a tag with formatting. * * @since 2.7.0 * @@ -894,7 +894,7 @@ function edit_tag_link( $link = '', $before = '', $after = '', $tag = null ) { $link = edit_term_link( $link, '', '', $tag, false ); /** - * Filter the anchor tag for the edit link for a tag (or term in another taxonomy). + * Filters the anchor tag for the edit link for a tag (or term in another taxonomy). * * @since 2.7.0 * @@ -944,7 +944,7 @@ function get_edit_term_link( $term_id, $taxonomy = '', $object_type = '' ) { } /** - * Filter the edit link for a term. + * Filters the edit link for a term. * * @since 3.1.0 * @@ -957,7 +957,7 @@ function get_edit_term_link( $term_id, $taxonomy = '', $object_type = '' ) { } /** - * Display or retrieve edit term link with formatting. + * Displays or retrieves the edit term link with formatting. * * @since 3.1.0 * @@ -985,7 +985,7 @@ function edit_term_link( $link = '', $before = '', $after = '', $term = null, $e $link = '' . $link . ''; /** - * Filter the anchor tag for the edit link of a term. + * Filters the anchor tag for the edit link of a term. * * @since 3.1.0 * @@ -1001,7 +1001,7 @@ function edit_term_link( $link = '', $before = '', $after = '', $term = null, $e } /** - * Retrieve permalink for search. + * Retrieves the permalink for a search. * * @since 3.0.0 * @@ -1030,7 +1030,7 @@ function get_search_link( $query = '' ) { } /** - * Filter the search permalink. + * Filters the search permalink. * * @since 3.0.0 * @@ -1041,7 +1041,7 @@ function get_search_link( $query = '' ) { } /** - * Retrieve the permalink for the feed of the search results. + * Retrieves the permalink for the search results feed. * * @since 2.5.0 * @@ -1068,7 +1068,7 @@ function get_search_feed_link($search_query = '', $feed = '') { } /** - * Filter the search feed link. + * Filters the search feed link. * * @since 2.5.0 * @@ -1080,7 +1080,7 @@ function get_search_feed_link($search_query = '', $feed = '') { } /** - * Retrieve the permalink for the comments feed of the search results. + * Retrieves the permalink for the search results comments feed. * * @since 2.5.0 * @@ -1153,7 +1153,7 @@ function get_post_type_archive_link( $post_type ) { } /** - * Filter the post type archive permalink. + * Filters the post type archive permalink. * * @since 3.1.0 * @@ -1164,7 +1164,7 @@ function get_post_type_archive_link( $post_type ) { } /** - * Retrieve the permalink for a post type archive feed. + * Retrieves the permalink for a post type archive feed. * * @since 3.1.0 * @@ -1191,7 +1191,7 @@ function get_post_type_archive_feed_link( $post_type, $feed = '' ) { } /** - * Filter the post type archive feed link. + * Filters the post type archive feed link. * * @since 3.1.0 * @@ -1202,7 +1202,7 @@ function get_post_type_archive_feed_link( $post_type, $feed = '' ) { } /** - * Retrieve URL used for the post preview. + * Retrieves the URL used for the post preview. * * Get the preview post URL. Allows additional query args to be appended. * @@ -1230,7 +1230,7 @@ function get_preview_post_link( $post = null, $query_args = array(), $preview_li } /** - * Filter the URL used for a post preview. + * Filters the URL used for a post preview. * * @since 2.0.5 * @since 4.0.0 Added the `$post` parameter. @@ -1242,7 +1242,7 @@ function get_preview_post_link( $post = null, $query_args = array(), $preview_li } /** - * Retrieve edit posts link for post. + * Retrieves the edit post link for post. * * Can be used within the WordPress loop or outside of it. Can be used with * pages, posts, attachments, and revisions. @@ -1279,7 +1279,7 @@ function get_edit_post_link( $id = 0, $context = 'display' ) { } /** - * Filter the post edit link. + * Filters the post edit link. * * @since 2.3.0 * @@ -1292,7 +1292,7 @@ function get_edit_post_link( $id = 0, $context = 'display' ) { } /** - * Display edit post link for post. + * Displays the edit post link for post. * * @since 1.0.0 * @since 4.4.0 The `$class` argument was added. @@ -1319,7 +1319,7 @@ function edit_post_link( $text = null, $before = '', $after = '', $id = 0, $clas $link = '' . $text . ''; /** - * Filter the post edit link anchor tag. + * Filters the post edit link anchor tag. * * @since 2.3.0 * @@ -1331,7 +1331,7 @@ function edit_post_link( $text = null, $before = '', $after = '', $id = 0, $clas } /** - * Retrieve delete posts link for post. + * Retrieves the delete posts link for post. * * Can be used within the WordPress loop or outside of it, with any post type. * @@ -1361,7 +1361,7 @@ function get_delete_post_link( $id = 0, $deprecated = '', $force_delete = false $delete_link = add_query_arg( 'action', $action, admin_url( sprintf( $post_type_object->_edit_link, $post->ID ) ) ); /** - * Filter the post delete link. + * Filters the post delete link. * * @since 2.9.0 * @@ -1373,7 +1373,7 @@ function get_delete_post_link( $id = 0, $deprecated = '', $force_delete = false } /** - * Retrieve edit comment link. + * Retrieves the edit comment link. * * @since 2.3.0 * @@ -1399,7 +1399,7 @@ function get_edit_comment_link( $comment_id = 0 ) { } /** - * Display edit comment link with formatting. + * Displays the edit comment link with formatting. * * @since 1.0.0 * @@ -1421,7 +1421,7 @@ function edit_comment_link( $text = null, $before = '', $after = '' ) { $link = '' . $text . ''; /** - * Filter the comment edit link anchor tag. + * Filters the comment edit link anchor tag. * * @since 2.3.0 * @@ -1433,7 +1433,7 @@ function edit_comment_link( $text = null, $before = '', $after = '' ) { } /** - * Display edit bookmark link. + * Displays the edit bookmark link. * * @since 2.7.0 * @@ -1460,7 +1460,7 @@ function get_edit_bookmark_link( $link = 0 ) { } /** - * Display edit bookmark link anchor content. + * Displays the edit bookmark link anchor content. * * @since 2.7.0 * @@ -1481,7 +1481,7 @@ function edit_bookmark_link( $link = '', $before = '', $after = '', $bookmark = $link = '' . $link . ''; /** - * Filter the bookmark edit link anchor tag. + * Filters the bookmark edit link anchor tag. * * @since 2.7.0 * @@ -1492,7 +1492,7 @@ function edit_bookmark_link( $link = '', $before = '', $after = '', $bookmark = } /** - * Retrieve edit user link + * Retrieves the edit user link. * * @since 3.5.0 * @@ -1530,7 +1530,7 @@ function get_edit_user_link( $user_id = null ) { // Navigation links /** - * Retrieve previous post that is adjacent to current post. + * Retrieves the previous post that is adjacent to the current post. * * @since 1.5.0 * @@ -1544,7 +1544,7 @@ function get_previous_post( $in_same_term = false, $excluded_terms = '', $taxono } /** - * Retrieve next post that is adjacent to current post. + * Retrieves the next post that is adjacent to the current post. * * @since 1.5.0 * @@ -1558,7 +1558,7 @@ function get_next_post( $in_same_term = false, $excluded_terms = '', $taxonomy = } /** - * Retrieve adjacent post. + * Retrieves the adjacent post. * * Can either be next or previous post. * @@ -1616,7 +1616,7 @@ function get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previo } /** - * Filter the IDs of terms excluded from adjacent post queries. + * Filters the IDs of terms excluded from adjacent post queries. * * The dynamic portion of the hook name, `$adjacent`, refers to the type * of adjacency, 'next' or 'previous'. @@ -1666,7 +1666,7 @@ function get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previo $order = $previous ? 'DESC' : 'ASC'; /** - * Filter the JOIN clause in the SQL for an adjacent post query. + * Filters the JOIN clause in the SQL for an adjacent post query. * * The dynamic portion of the hook name, `$adjacent`, refers to the type * of adjacency, 'next' or 'previous'. @@ -1683,7 +1683,7 @@ function get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previo $join = apply_filters( "get_{$adjacent}_post_join", $join, $in_same_term, $excluded_terms, $taxonomy, $post ); /** - * Filter the WHERE clause in the SQL for an adjacent post query. + * Filters the WHERE clause in the SQL for an adjacent post query. * * The dynamic portion of the hook name, `$adjacent`, refers to the type * of adjacency, 'next' or 'previous'. @@ -1700,7 +1700,7 @@ function get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previo $where = apply_filters( "get_{$adjacent}_post_where", $wpdb->prepare( "WHERE p.post_date $op %s AND p.post_type = %s $where", $current_post_date, $post->post_type ), $in_same_term, $excluded_terms, $taxonomy, $post ); /** - * Filter the ORDER BY clause in the SQL for an adjacent post query. + * Filters the ORDER BY clause in the SQL for an adjacent post query. * * The dynamic portion of the hook name, `$adjacent`, refers to the type * of adjacency, 'next' or 'previous'. @@ -1735,7 +1735,7 @@ function get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previo } /** - * Get adjacent post relational link. + * Retrieves the adjacent post relational link. * * Can either be next or previous post relational link. * @@ -1774,7 +1774,7 @@ function get_adjacent_post_rel_link( $title = '%title', $in_same_term = false, $ $adjacent = $previous ? 'previous' : 'next'; /** - * Filter the adjacent post relational link. + * Filters the adjacent post relational link. * * The dynamic portion of the hook name, `$adjacent`, refers to the type * of adjacency, 'next' or 'previous'. @@ -1787,7 +1787,7 @@ function get_adjacent_post_rel_link( $title = '%title', $in_same_term = false, $ } /** - * Display relational links for the posts adjacent to the current post. + * Displays the relational links for the posts adjacent to the current post. * * @since 2.8.0 * @@ -1802,7 +1802,7 @@ function adjacent_posts_rel_link( $title = '%title', $in_same_term = false, $exc } /** - * Display relational links for the posts adjacent to the current post for single post pages. + * Displays relational links for the posts adjacent to the current post for single post pages. * * This is meant to be attached to actions like 'wp_head'. Do not call this directly in plugins or theme templates. * @since 3.0.0 @@ -1816,7 +1816,7 @@ function adjacent_posts_rel_link_wp_head() { } /** - * Display relational link for the next post adjacent to the current post. + * Displays the relational link for the next post adjacent to the current post. * * @since 2.8.0 * @@ -1830,7 +1830,7 @@ function next_post_rel_link( $title = '%title', $in_same_term = false, $excluded } /** - * Display relational link for the previous post adjacent to the current post. + * Displays the relational link for the previous post adjacent to the current post. * * @since 2.8.0 * @@ -1844,7 +1844,7 @@ function prev_post_rel_link( $title = '%title', $in_same_term = false, $excluded } /** - * Retrieve boundary post. + * Retrieves the boundary post. * * Boundary being either the first or last post by publish date within the constraints specified * by $in_same_term or $excluded_terms. @@ -1902,7 +1902,7 @@ function get_boundary_post( $in_same_term = false, $excluded_terms = '', $start } /** - * Get previous post link that is adjacent to the current post. + * Retrieves the previous post link that is adjacent to the current post. * * @since 3.7.0 * @@ -1918,9 +1918,10 @@ function get_previous_post_link( $format = '« %link', $link = '%title', $i } /** - * Display previous post link that is adjacent to the current post. + * Displays the previous post link that is adjacent to the current post. * * @since 1.5.0 + * * @see get_previous_post_link() * * @param string $format Optional. Link anchor format. @@ -1934,7 +1935,7 @@ function previous_post_link( $format = '« %link', $link = '%title', $in_sa } /** - * Get next post link that is adjacent to the current post. + * Retrieves the next post link that is adjacent to the current post. * * @since 3.7.0 * @@ -1950,7 +1951,7 @@ function get_next_post_link( $format = '%link »', $link = '%title', $in_sa } /** - * Display next post link that is adjacent to the current post. + * Displays the next post link that is adjacent to the current post. * * @since 1.5.0 * @see get_next_post_link() @@ -1966,7 +1967,7 @@ function next_post_link( $format = '%link »', $link = '%title', $in_same_t } /** - * Get adjacent post link. + * Retrieves the adjacent post link. * * Can be either next post link or previous. * @@ -2011,7 +2012,7 @@ function get_adjacent_post_link( $format, $link, $in_same_term = false, $exclude $adjacent = $previous ? 'previous' : 'next'; /** - * Filter the adjacent post link. + * Filters the adjacent post link. * * The dynamic portion of the hook name, `$adjacent`, refers to the type * of adjacency, 'next' or 'previous'. @@ -2029,7 +2030,7 @@ function get_adjacent_post_link( $format, $link, $in_same_term = false, $exclude } /** - * Display adjacent post link. + * Displays the adjacent post link. * * Can be either next post link or previous. * @@ -2047,7 +2048,7 @@ function adjacent_post_link( $format, $link, $in_same_term = false, $excluded_te } /** - * Retrieve links for page numbers. + * Retrieves the link for a page number. * * @since 1.5.0 * @@ -2108,7 +2109,7 @@ function get_pagenum_link($pagenum = 1, $escape = true ) { } /** - * Filter the page number link for the current request. + * Filters the page number link for the current request. * * @since 2.5.0 * @@ -2123,7 +2124,7 @@ function get_pagenum_link($pagenum = 1, $escape = true ) { } /** - * Retrieve next posts page link. + * Retrieves the next posts page link. * * Backported from 2.1.3 to 2.0.10. * @@ -2147,7 +2148,7 @@ function get_next_posts_page_link($max_page = 0) { } /** - * Display or return the next posts page link. + * Displays or retrieves the next posts page link. * * @since 0.71 * @@ -2165,7 +2166,7 @@ function next_posts( $max_page = 0, $echo = true ) { } /** - * Return the next posts page link. + * Retrieves the next posts page link. * * @since 2.7.0 * @@ -2205,7 +2206,7 @@ function get_next_posts_link( $label = null, $max_page = 0 ) { } /** - * Display the next posts page link. + * Displays the next posts page link. * * @since 0.71 * @@ -2217,7 +2218,7 @@ function next_posts_link( $label = null, $max_page = 0 ) { } /** - * Retrieve previous posts page link. + * Retrieves the previous posts page link. * * Will only return string, if not on a single page or post. * @@ -2241,7 +2242,7 @@ function get_previous_posts_page_link() { } /** - * Display or return the previous posts page link. + * Displays or retrieves the previous posts page link. * * @since 0.71 * @@ -2258,7 +2259,7 @@ function previous_posts( $echo = true ) { } /** - * Return the previous posts page link. + * Retrieves the previous posts page link. * * @since 2.7.0 * @@ -2287,7 +2288,7 @@ function get_previous_posts_link( $label = null ) { } /** - * Display the previous posts page link. + * Displays the previous posts page link. * * @since 0.71 * @@ -2298,7 +2299,7 @@ function previous_posts_link( $label = null ) { } /** - * Return post pages link navigation for previous and next pages. + * Retrieves the post pages link navigation for previous and next pages. * * @since 2.8.0 * @@ -2339,7 +2340,7 @@ function get_posts_nav_link( $args = array() ) { } /** - * Display post pages link navigation for previous and next pages. + * Displays the post pages link navigation for previous and next pages. * * @since 0.71 * @@ -2353,7 +2354,7 @@ function posts_nav_link( $sep = '', $prelabel = '', $nxtlabel = '' ) { } /** - * Return navigation to next/previous post when applicable. + * Retrieves the navigation to next/previous post, when applicable. * * @since 4.1.0 * @since 4.4.0 Introduced the `in_same_term`, `excluded_terms`, and `taxonomy` arguments. @@ -2407,7 +2408,7 @@ function get_the_post_navigation( $args = array() ) { } /** - * Display navigation to next/previous post when applicable. + * Displays the navigation to next/previous post, when applicable. * * @since 4.1.0 * @@ -2419,7 +2420,7 @@ function the_post_navigation( $args = array() ) { } /** - * Return navigation to next/previous set of posts when applicable. + * Returns the navigation to next/previous set of posts, when applicable. * * @since 4.1.0 * @@ -2466,7 +2467,7 @@ function get_the_posts_navigation( $args = array() ) { } /** - * Display navigation to next/previous set of posts when applicable. + * Displays the navigation to next/previous set of posts, when applicable. * * @since 4.1.0 * @@ -2478,8 +2479,7 @@ function the_posts_navigation( $args = array() ) { } /** - * Return a paginated navigation to next/previous set of posts, - * when applicable. + * Retrieves a paginated navigation to next/previous set of posts, when applicable. * * @since 4.1.0 * @@ -2520,8 +2520,7 @@ function get_the_posts_pagination( $args = array() ) { } /** - * Display a paginated navigation to next/previous set of posts, - * when applicable. + * Displays a paginated navigation to next/previous set of posts, when applicable. * * @since 4.1.0 * @@ -2555,7 +2554,7 @@ function _navigation_markup( $links, $class = 'posts-navigation', $screen_reader '; /** - * Filter the navigation markup template. + * Filters the navigation markup template. * * Note: The filtered template HTML must contain specifiers for the navigation * class (%1$s), the screen-reader-text value (%2$s), and placement of the @@ -2578,7 +2577,7 @@ function _navigation_markup( $links, $class = 'posts-navigation', $screen_reader } /** - * Retrieve comments page number link. + * Retrieves the comments page number link. * * @since 2.7.0 * @@ -2612,7 +2611,7 @@ function get_comments_pagenum_link( $pagenum = 1, $max_page = 0 ) { $result .= '#comments'; /** - * Filter the comments page number link for the current request. + * Filters the comments page number link for the current request. * * @since 2.7.0 * @@ -2622,7 +2621,7 @@ function get_comments_pagenum_link( $pagenum = 1, $max_page = 0 ) { } /** - * Return the link to next comments page. + * Retrieves the link to the next comments page. * * @since 2.7.1 * @@ -2659,7 +2658,7 @@ function get_next_comments_link( $label = '', $max_page = 0 ) { $label = __('Newer Comments »'); /** - * Filter the anchor tag attributes for the next comments page link. + * Filters the anchor tag attributes for the next comments page link. * * @since 2.7.0 * @@ -2669,7 +2668,7 @@ function get_next_comments_link( $label = '', $max_page = 0 ) { } /** - * Display the link to next comments page. + * Displays the link to the next comments page. * * @since 2.7.0 * @@ -2681,7 +2680,7 @@ function next_comments_link( $label = '', $max_page = 0 ) { } /** - * Return the previous comments page link. + * Retrieves the link to the previous comments page. * * @since 2.7.1 * @@ -2713,7 +2712,7 @@ function get_previous_comments_link( $label = '' ) { } /** - * Display the previous comments page link. + * Displays the link to the previous comments page. * * @since 2.7.0 * @@ -2724,7 +2723,7 @@ function previous_comments_link( $label = '' ) { } /** - * Create pagination links for the comments on the current post. + * Displays or retrieves pagination links for the comments on the current post. * * @see paginate_links() * @since 2.7.0 @@ -2765,7 +2764,7 @@ function paginate_comments_links($args = array()) { } /** - * Returns navigation to next/previous set of comments when applicable. + * Retrieves navigation to next/previous set of comments, when applicable. * * @since 4.4.0 * @@ -2807,7 +2806,7 @@ function get_the_comments_navigation( $args = array() ) { } /** - * Displays navigation to next/previous set of comments when applicable. + * Displays navigation to next/previous set of comments, when applicable. * * @since 4.4.0 * @@ -2818,8 +2817,7 @@ function the_comments_navigation( $args = array() ) { } /** - * Returns a paginated navigation to next/previous set of comments, - * when applicable. + * Retrieves a paginated navigation to next/previous set of comments, when applicable. * * @since 4.4.0 * @@ -2852,8 +2850,7 @@ function get_the_comments_pagination( $args = array() ) { } /** - * Displays a paginated navigation to next/previous set of comments, - * when applicable. + * Displays a paginated navigation to next/previous set of comments, when applicable. * * @since 4.4.0 * @@ -2864,9 +2861,7 @@ function the_comments_pagination( $args = array() ) { } /** - * Retrieve the Press This bookmarklet link. - * - * Use this in 'a' element 'href' attribute. + * Retrieves the Press This bookmarklet link. * * @since 2.6.0 * @@ -2884,7 +2879,7 @@ function get_shortcut_link() { $link = ''; if ( $is_IE ) { - /** + /* * Return the old/shorter bookmarklet code for MSIE 8 and lower, * since they only support a max length of ~2000 characters for * bookmark[let] URLs, which is way to small for our smarter one. @@ -2916,7 +2911,7 @@ function get_shortcut_link() { $link = str_replace( array( "\r", "\n", "\t" ), '', $link ); /** - * Filter the Press This bookmarklet link. + * Filters the Press This bookmarklet link. * * @since 2.6.0 * @@ -2926,7 +2921,7 @@ function get_shortcut_link() { } /** - * Retrieve the URL for the current site where the front end is accessible. + * Retrieves the URL for the current site where the front end is accessible. * * Returns the 'home' option with the appropriate protocol, 'https' if * {@see is_ssl()} and 'http' otherwise. If `$scheme` is 'http' or 'https', @@ -2944,7 +2939,7 @@ function home_url( $path = '', $scheme = null ) { } /** - * Retrieve the URL for a given site where the front end is accessible. + * Retrieves the URL for a given site where the front end is accessible. * * Returns the 'home' option with the appropriate protocol, 'https' if * {@see is_ssl()} and 'http' otherwise. If `$scheme` is 'http' or 'https', @@ -2987,7 +2982,7 @@ function get_home_url( $blog_id = null, $path = '', $scheme = null ) { $url .= '/' . ltrim( $path, '/' ); /** - * Filter the home URL. + * Filters the home URL. * * @since 3.0.0 * @@ -3001,7 +2996,7 @@ function get_home_url( $blog_id = null, $path = '', $scheme = null ) { } /** - * Retrieve the URL for the current site where WordPress application files + * Retrieves the URL for the current site where WordPress application files * (e.g. wp-blog-header.php or the wp-admin/ folder) are accessible. * * Returns the 'site_url' option with the appropriate protocol, 'https' if @@ -3019,7 +3014,7 @@ function site_url( $path = '', $scheme = null ) { } /** - * Retrieve the URL for a given site where WordPress application files + * Retrieves the URL for a given site where WordPress application files * (e.g. wp-blog-header.php or the wp-admin/ folder) are accessible. * * Returns the 'site_url' option with the appropriate protocol, 'https' if @@ -3050,7 +3045,7 @@ function get_site_url( $blog_id = null, $path = '', $scheme = null ) { $url .= '/' . ltrim( $path, '/' ); /** - * Filter the site URL. + * Filters the site URL. * * @since 2.7.0 * @@ -3064,7 +3059,7 @@ function get_site_url( $blog_id = null, $path = '', $scheme = null ) { } /** - * Retrieve the url to the admin area for the current site. + * Retrieves the URL to the admin area for the current site. * * @since 2.6.0 * @@ -3077,7 +3072,7 @@ function admin_url( $path = '', $scheme = 'admin' ) { } /** - * Retrieves the url to the admin area for a given site. + * Retrieves the URL to the admin area for a given site. * * @since 3.0.0 * @@ -3095,7 +3090,7 @@ function get_admin_url( $blog_id = null, $path = '', $scheme = 'admin' ) { $url .= ltrim( $path, '/' ); /** - * Filter the admin area URL. + * Filters the admin area URL. * * @since 2.8.0 * @@ -3107,7 +3102,7 @@ function get_admin_url( $blog_id = null, $path = '', $scheme = 'admin' ) { } /** - * Retrieve the url to the includes directory. + * Retrieves the URL to the includes directory. * * @since 2.6.0 * @@ -3122,7 +3117,7 @@ function includes_url( $path = '', $scheme = null ) { $url .= ltrim($path, '/'); /** - * Filter the URL to the includes directory. + * Filters the URL to the includes directory. * * @since 2.8.0 * @@ -3134,7 +3129,7 @@ function includes_url( $path = '', $scheme = null ) { } /** - * Retrieve the url to the content directory. + * Retrieves the URL to the content directory. * * @since 2.6.0 * @@ -3148,7 +3143,7 @@ function content_url($path = '') { $url .= '/' . ltrim($path, '/'); /** - * Filter the URL to the content directory. + * Filters the URL to the content directory. * * @since 2.8.0 * @@ -3160,7 +3155,7 @@ function content_url($path = '') { } /** - * Retrieve a URL within the plugins or mu-plugins directory. + * Retrieves a URL within the plugins or mu-plugins directory. * * Defaults to the plugins directory URL if no arguments are supplied. * @@ -3197,7 +3192,7 @@ function plugins_url( $path = '', $plugin = '' ) { $url .= '/' . ltrim($path, '/'); /** - * Filter the URL to the plugins directory. + * Filters the URL to the plugins directory. * * @since 2.8.0 * @@ -3211,7 +3206,7 @@ function plugins_url( $path = '', $plugin = '' ) { } /** - * Retrieve the site url for the current network. + * Retrieves the site URL for the current network. * * Returns the site url with the appropriate protocol, 'https' if * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is @@ -3238,7 +3233,7 @@ function network_site_url( $path = '', $scheme = null ) { $url .= ltrim( $path, '/' ); /** - * Filter the network site URL. + * Filters the network site URL. * * @since 3.0.0 * @@ -3252,7 +3247,7 @@ function network_site_url( $path = '', $scheme = null ) { } /** - * Retrieves the home url for the current network. + * Retrieves the home URL for the current network. * * Returns the home url with the appropriate protocol, 'https' {@see is_ssl()} * and 'http' otherwise. If `$scheme` is 'http' or 'https', `is_ssl()` is @@ -3284,7 +3279,7 @@ function network_home_url( $path = '', $scheme = null ) { $url .= ltrim( $path, '/' ); /** - * Filter the network home URL. + * Filters the network home URL. * * @since 3.0.0 * @@ -3298,7 +3293,7 @@ function network_home_url( $path = '', $scheme = null ) { } /** - * Retrieve the url to the admin area for the network. + * Retrieves the URL to the admin area for the network. * * @since 3.0.0 * @@ -3316,7 +3311,7 @@ function network_admin_url( $path = '', $scheme = 'admin' ) { $url .= ltrim($path, '/'); /** - * Filter the network admin URL. + * Filters the network admin URL. * * @since 3.0.0 * @@ -3328,7 +3323,7 @@ function network_admin_url( $path = '', $scheme = 'admin' ) { } /** - * Retrieve the url to the admin area for the current user. + * Retrieves the URL to the admin area for the current user. * * @since 3.0.0 * @@ -3343,7 +3338,7 @@ function user_admin_url( $path = '', $scheme = 'admin' ) { $url .= ltrim($path, '/'); /** - * Filter the user admin URL for the current user. + * Filters the user admin URL for the current user. * * @since 3.1.0 * @@ -3355,7 +3350,7 @@ function user_admin_url( $path = '', $scheme = 'admin' ) { } /** - * Retrieve the url to the admin area for either the current site or the network depending on context. + * Retrieves the URL to the admin area for either the current site or the network depending on context. * * @since 3.1.0 * @@ -3407,7 +3402,7 @@ function set_url_scheme( $url, $scheme = null ) { } /** - * Filter the resulting URL after setting the scheme. + * Filters the resulting URL after setting the scheme. * * @since 3.4.0 * @@ -3420,7 +3415,7 @@ function set_url_scheme( $url, $scheme = null ) { } /** - * Get the URL to the user's dashboard. + * Retrieves the URL to the user's dashboard. * * If a user does not belong to any site, the global user dashboard is used. If the user belongs to the current site, * the dashboard for the current site is returned. If the user cannot edit the current site, the dashboard to the user's @@ -3455,7 +3450,7 @@ function get_dashboard_url( $user_id = 0, $path = '', $scheme = 'admin' ) { } /** - * Filter the dashboard URL for a user. + * Filters the dashboard URL for a user. * * @since 3.1.0 * @@ -3469,7 +3464,7 @@ function get_dashboard_url( $user_id = 0, $path = '', $scheme = 'admin' ) { } /** - * Get the URL to the user's profile editor. + * Retrieves the URL to the user's profile editor. * * @since 3.1.0 * @@ -3489,7 +3484,7 @@ function get_edit_profile_url( $user_id = 0, $scheme = 'admin' ) { $url = get_dashboard_url( $user_id, 'profile.php', $scheme ); /** - * Filter the URL for a user's profile editor. + * Filters the URL for a user's profile editor. * * @since 3.1.0 * @@ -3502,7 +3497,7 @@ function get_edit_profile_url( $user_id = 0, $scheme = 'admin' ) { } /** - * Output rel=canonical for singular queries. + * Outputs rel=canonical for singular queries. * * @since 2.9.0 */ @@ -3534,7 +3529,7 @@ function rel_canonical() { } /** - * Return a shortlink for a post, page, attachment, or a site. + * Returns a shortlink for a post, page, attachment, or site. * * This function exists to provide a shortlink tag that all themes and plugins can target. A plugin must hook in to * provide the actual shortlinks. Default shortlink support is limited to providing ?p= style links for posts. @@ -3553,7 +3548,7 @@ function rel_canonical() { */ function wp_get_shortlink($id = 0, $context = 'post', $allow_slugs = true) { /** - * Filter whether to preempt generating a shortlink for the given post. + * Filters whether to preempt generating a shortlink for the given post. * * Passing a truthy value to the filter will effectively short-circuit the * shortlink-generation process, returning that value instead. @@ -3595,7 +3590,7 @@ function wp_get_shortlink($id = 0, $context = 'post', $allow_slugs = true) { } /** - * Filter the shortlink for a post. + * Filters the shortlink for a post. * * @since 3.0.0 * @@ -3608,9 +3603,9 @@ function wp_get_shortlink($id = 0, $context = 'post', $allow_slugs = true) { } /** - * Inject rel=shortlink into head if a shortlink is defined for the current page. + * Injects rel=shortlink into the head if a shortlink is defined for the current page. * - * Attached to the wp_head action. + * Attached to the wp_head action. * * @since 3.0.0 */ @@ -3624,7 +3619,7 @@ function wp_shortlink_wp_head() { } /** - * Send a Link: rel=shortlink header if a shortlink is defined for the current page. + * Sends a Link: rel=shortlink header if a shortlink is defined for the current page. * * Attached to the wp action. * @@ -3643,7 +3638,7 @@ function wp_shortlink_header() { } /** - * Display the Short Link for a Post + * Displays the shortlink for a post. * * Must be called from inside "The Loop" * @@ -3671,7 +3666,7 @@ function the_shortlink( $text = '', $title = '', $before = '', $after = '' ) { $link = '' . $text . ''; /** - * Filter the shortlink anchor tag for a post. + * Filters the short link anchor tag for a post. * * @since 3.0.0 * @@ -3687,7 +3682,7 @@ function the_shortlink( $text = '', $title = '', $before = '', $after = '' ) { /** - * Retrieve the avatar URL. + * Retrieves the avatar URL. * * @since 4.2.0 * @@ -3719,7 +3714,7 @@ function get_avatar_url( $id_or_email, $args = null ) { } /** - * Retrieve default data about the avatar. + * Retrieves default data about the avatar. * * @since 4.2.0 * @@ -3816,7 +3811,7 @@ function get_avatar_data( $id_or_email, $args = null ) { $args['found_avatar'] = false; /** - * Filter whether to retrieve the avatar URL early. + * Filters whether to retrieve the avatar URL early. * * Passing a non-null value in the 'url' member of the return array will * effectively short circuit get_avatar_data(), passing the value through @@ -3918,7 +3913,7 @@ function get_avatar_data( $id_or_email, $args = null ) { ); /** - * Filter the avatar URL. + * Filters the avatar URL. * * @since 4.2.0 * @@ -3930,7 +3925,7 @@ function get_avatar_data( $id_or_email, $args = null ) { $args['url'] = apply_filters( 'get_avatar_url', $url, $id_or_email, $args ); /** - * Filter the avatar data. + * Filters the avatar data. * * @since 4.2.0 *