Docs: Improve documentation for various feed link functions and filters.

Props atachibana, SergeyBiryukov.
Fixes #47862.
Built from https://develop.svn.wordpress.org/trunk@45781


git-svn-id: http://core.svn.wordpress.org/trunk@45592 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov 2019-08-11 17:21:57 +00:00
parent b7e7a5321b
commit e6a4b884f5
3 changed files with 38 additions and 24 deletions

View File

@ -398,7 +398,8 @@ function get_author_posts_url( $author_id, $author_nicename = '' ) {
* parameter of the link. Default empty. * parameter of the link. Default empty.
* @type string $feed_image If not empty, show a link to the author's feed and use this image URL as * @type string $feed_image If not empty, show a link to the author's feed and use this image URL as
* clickable anchor. Default empty. * clickable anchor. Default empty.
* @type string $feed_type The feed type to link to, such as 'rss2'. Defaults to default feed type. * @type string $feed_type The feed type to link to. Possible values include 'rss2', 'atom'.
* Default is the value of get_default_feed().
* @type bool $echo Whether to output the result or instead return it. Default true. * @type bool $echo Whether to output the result or instead return it. Default true.
* @type string $style If 'list', each author is wrapped in an `<li>` element, otherwise the authors * @type string $style If 'list', each author is wrapped in an `<li>` element, otherwise the authors
* will be separated by commas. * will be separated by commas.

View File

@ -584,7 +584,8 @@ function get_day_link( $year, $month, $day ) {
* @since 3.0.0 * @since 3.0.0
* *
* @param string $anchor The link's anchor text. * @param string $anchor The link's anchor text.
* @param string $feed Optional. Feed type. Default empty. * @param string $feed Optional. Feed type. Possible values include 'rss2', 'atom'.
* Default is the value of get_default_feed().
*/ */
function the_feed_link( $anchor, $feed = '' ) { function the_feed_link( $anchor, $feed = '' ) {
$link = '<a href="' . esc_url( get_feed_link( $feed ) ) . '">' . $anchor . '</a>'; $link = '<a href="' . esc_url( get_feed_link( $feed ) ) . '">' . $anchor . '</a>';
@ -595,8 +596,8 @@ function the_feed_link( $anchor, $feed = '' ) {
* @since 3.0.0 * @since 3.0.0
* *
* @param string $link The complete anchor tag for a feed link. * @param string $link The complete anchor tag for a feed link.
* @param string $feed The feed type, or an empty string for the * @param string $feed The feed type. Possible values include 'rss2', 'atom',
* default feed type. * or an empty string for the default feed type.
*/ */
echo apply_filters( 'the_feed_link', $link, $feed ); echo apply_filters( 'the_feed_link', $link, $feed );
} }
@ -608,7 +609,8 @@ function the_feed_link( $anchor, $feed = '' ) {
* *
* @global WP_Rewrite $wp_rewrite WordPress rewrite component. * @global WP_Rewrite $wp_rewrite WordPress rewrite component.
* *
* @param string $feed Optional. Feed type. Default empty. * @param string $feed Optional. Feed type. Possible values include 'rss2', 'atom'.
* Default is the value of get_default_feed().
* @return string The feed permalink. * @return string The feed permalink.
*/ */
function get_feed_link( $feed = '' ) { function get_feed_link( $feed = '' ) {
@ -646,7 +648,8 @@ function get_feed_link( $feed = '' ) {
* @since 1.5.0 * @since 1.5.0
* *
* @param string $output The feed permalink. * @param string $output The feed permalink.
* @param string $feed Feed type. * @param string $feed The feed type. Possible values include 'rss2', 'atom',
* or an empty string for the default feed type.
*/ */
return apply_filters( 'feed_link', $output, $feed ); return apply_filters( 'feed_link', $output, $feed );
} }
@ -657,7 +660,8 @@ function get_feed_link( $feed = '' ) {
* @since 2.2.0 * @since 2.2.0
* *
* @param int $post_id Optional. Post ID. Default is the ID of the global `$post`. * @param int $post_id Optional. Post ID. Default is the ID of the global `$post`.
* @param string $feed Optional. Feed type. Default empty. * @param string $feed Optional. Feed type. Possible values include 'rss2', 'atom'.
* Default is the value of get_default_feed().
* @return string The permalink for the comments feed for the given post. * @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 = '' ) {
@ -743,7 +747,8 @@ function get_post_comments_feed_link( $post_id = 0, $feed = '' ) {
* *
* @param string $link_text Optional. Descriptive link text. Default 'Comments Feed'. * @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 int $post_id Optional. Post ID. Default is the ID of the global `$post`.
* @param string $feed Optional. Feed format. Default empty. * @param string $feed Optional. Feed type. Possible values include 'rss2', 'atom'.
* Default is the value of get_default_feed().
*/ */
function post_comments_feed_link( $link_text = '', $post_id = '', $feed = '' ) { function post_comments_feed_link( $link_text = '', $post_id = '', $feed = '' ) {
$url = get_post_comments_feed_link( $post_id, $feed ); $url = get_post_comments_feed_link( $post_id, $feed );
@ -759,7 +764,8 @@ function post_comments_feed_link( $link_text = '', $post_id = '', $feed = '' ) {
* *
* @param string $link The complete anchor tag for the comment feed link. * @param string $link The complete anchor tag for the comment feed link.
* @param int $post_id Post ID. * @param int $post_id Post ID.
* @param string $feed The feed type, or an empty string for the default feed type. * @param string $feed The feed type. Possible values include 'rss2', 'atom',
* or an empty string for the default feed type.
*/ */
echo apply_filters( 'post_comments_feed_link_html', $link, $post_id, $feed ); echo apply_filters( 'post_comments_feed_link_html', $link, $post_id, $feed );
} }
@ -773,7 +779,8 @@ function post_comments_feed_link( $link_text = '', $post_id = '', $feed = '' ) {
* @since 2.5.0 * @since 2.5.0
* *
* @param int $author_id Author ID. * @param int $author_id Author ID.
* @param string $feed Optional. Feed type. Default empty. * @param string $feed Optional. Feed type. Possible values include 'rss2', 'atom'.
* Default is the value of get_default_feed().
* @return string Link to the feed for the author specified by $author_id. * @return string Link to the feed for the author specified by $author_id.
*/ */
function get_author_feed_link( $author_id, $feed = '' ) { function get_author_feed_link( $author_id, $feed = '' ) {
@ -803,7 +810,7 @@ function get_author_feed_link( $author_id, $feed = '' ) {
* @since 1.5.1 * @since 1.5.1
* *
* @param string $link The author feed link. * @param string $link The author feed link.
* @param string $feed Feed type. * @param string $feed Feed type. Possible values include 'rss2', 'atom'.
*/ */
$link = apply_filters( 'author_feed_link', $link, $feed ); $link = apply_filters( 'author_feed_link', $link, $feed );
@ -819,7 +826,8 @@ function get_author_feed_link( $author_id, $feed = '' ) {
* @since 2.5.0 * @since 2.5.0
* *
* @param int $cat_id Category ID. * @param int $cat_id Category ID.
* @param string $feed Optional. Feed type. Default empty. * @param string $feed Optional. Feed type. Possible values include 'rss2', 'atom'.
* Default is the value of get_default_feed().
* @return string Link to the feed for the category specified by $cat_id. * @return string Link to the feed for the category specified by $cat_id.
*/ */
function get_category_feed_link( $cat_id, $feed = '' ) { function get_category_feed_link( $cat_id, $feed = '' ) {
@ -836,7 +844,8 @@ function get_category_feed_link( $cat_id, $feed = '' ) {
* *
* @param int $term_id Term ID. * @param int $term_id Term ID.
* @param string $taxonomy Optional. Taxonomy of `$term_id`. Default 'category'. * @param string $taxonomy Optional. Taxonomy of `$term_id`. Default 'category'.
* @param string $feed Optional. Feed type. Default empty. * @param string $feed Optional. Feed type. Possible values include 'rss2', 'atom'.
* Default is the value of get_default_feed().
* @return string|false Link to the feed for the term specified by $term_id and $taxonomy. * @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 = '' ) { function get_term_feed_link( $term_id, $taxonomy = 'category', $feed = '' ) {
@ -881,7 +890,7 @@ function get_term_feed_link( $term_id, $taxonomy = 'category', $feed = '' ) {
* @since 1.5.1 * @since 1.5.1
* *
* @param string $link The category feed link. * @param string $link The category feed link.
* @param string $feed Feed type. * @param string $feed Feed type. Possible values include 'rss2', 'atom'.
*/ */
$link = apply_filters( 'category_feed_link', $link, $feed ); $link = apply_filters( 'category_feed_link', $link, $feed );
} elseif ( 'post_tag' == $taxonomy ) { } elseif ( 'post_tag' == $taxonomy ) {
@ -891,7 +900,7 @@ function get_term_feed_link( $term_id, $taxonomy = 'category', $feed = '' ) {
* @since 2.3.0 * @since 2.3.0
* *
* @param string $link The tag feed link. * @param string $link The tag feed link.
* @param string $feed Feed type. * @param string $feed Feed type. Possible values include 'rss2', 'atom'.
*/ */
$link = apply_filters( 'tag_feed_link', $link, $feed ); $link = apply_filters( 'tag_feed_link', $link, $feed );
} else { } else {
@ -900,8 +909,8 @@ function get_term_feed_link( $term_id, $taxonomy = 'category', $feed = '' ) {
* *
* @since 3.0.0 * @since 3.0.0
* *
* @param string $link The taxonomy feed link. * @param string $link The taxonomy feed link.
* @param string $feed Feed type. * @param string $feed Feed type. Possible values include 'rss2', 'atom'.
* @param string $taxonomy The taxonomy name. * @param string $taxonomy The taxonomy name.
*/ */
$link = apply_filters( 'taxonomy_feed_link', $link, $feed, $taxonomy ); $link = apply_filters( 'taxonomy_feed_link', $link, $feed, $taxonomy );
@ -916,7 +925,8 @@ function get_term_feed_link( $term_id, $taxonomy = 'category', $feed = '' ) {
* @since 2.3.0 * @since 2.3.0
* *
* @param int $tag_id Tag ID. * @param int $tag_id Tag ID.
* @param string $feed Optional. Feed type. Default empty. * @param string $feed Optional. Feed type. Possible values include 'rss2', 'atom'.
* Default is the value of get_default_feed().
* @return string The feed permalink for the given tag. * @return string The feed permalink for the given tag.
*/ */
function get_tag_feed_link( $tag_id, $feed = '' ) { function get_tag_feed_link( $tag_id, $feed = '' ) {
@ -1120,7 +1130,8 @@ function get_search_link( $query = '' ) {
* @global WP_Rewrite $wp_rewrite WordPress rewrite component. * @global WP_Rewrite $wp_rewrite WordPress rewrite component.
* *
* @param string $search_query Optional. Search query. Default empty. * @param string $search_query Optional. Search query. Default empty.
* @param string $feed Optional. Feed type. Default empty. * @param string $feed Optional. Feed type. Possible values include 'rss2', 'atom'.
* Default is the value of get_default_feed().
* @return string The search results feed permalink. * @return string The search results feed permalink.
*/ */
function get_search_feed_link( $search_query = '', $feed = '' ) { function get_search_feed_link( $search_query = '', $feed = '' ) {
@ -1146,7 +1157,7 @@ function get_search_feed_link( $search_query = '', $feed = '' ) {
* @since 2.5.0 * @since 2.5.0
* *
* @param string $link Search feed link. * @param string $link Search feed link.
* @param string $feed Feed type. * @param string $feed Feed type. Possible values include 'rss2', 'atom'.
* @param string $type The search type. One of 'posts' or 'comments'. * @param string $type The search type. One of 'posts' or 'comments'.
*/ */
return apply_filters( 'search_feed_link', $link, $feed, 'posts' ); return apply_filters( 'search_feed_link', $link, $feed, 'posts' );
@ -1160,7 +1171,8 @@ function get_search_feed_link( $search_query = '', $feed = '' ) {
* @global WP_Rewrite $wp_rewrite WordPress rewrite component. * @global WP_Rewrite $wp_rewrite WordPress rewrite component.
* *
* @param string $search_query Optional. Search query. Default empty. * @param string $search_query Optional. Search query. Default empty.
* @param string $feed Optional. Feed type. Default empty. * @param string $feed Optional. Feed type. Possible values include 'rss2', 'atom'.
* Default is the value of get_default_feed().
* @return string The comments feed search results permalink. * @return string The comments feed search results permalink.
*/ */
function get_search_comments_feed_link( $search_query = '', $feed = '' ) { function get_search_comments_feed_link( $search_query = '', $feed = '' ) {
@ -1249,7 +1261,8 @@ function get_post_type_archive_link( $post_type ) {
* @since 3.1.0 * @since 3.1.0
* *
* @param string $post_type Post type * @param string $post_type Post type
* @param string $feed Optional. Feed type. Default empty. * @param string $feed Optional. Feed type. Possible values include 'rss2', 'atom'.
* Default is the value of get_default_feed().
* @return string|false The post type feed permalink. * @return string|false The post type feed permalink.
*/ */
function get_post_type_archive_feed_link( $post_type, $feed = '' ) { function get_post_type_archive_feed_link( $post_type, $feed = '' ) {
@ -1280,7 +1293,7 @@ function get_post_type_archive_feed_link( $post_type, $feed = '' ) {
* @since 3.1.0 * @since 3.1.0
* *
* @param string $link The post type archive feed link. * @param string $link The post type archive feed link.
* @param string $feed Feed type. * @param string $feed Feed type. Possible values include 'rss2', 'atom'.
*/ */
return apply_filters( 'post_type_archive_feed_link', $link, $feed ); return apply_filters( 'post_type_archive_feed_link', $link, $feed );
} }

View File

@ -13,7 +13,7 @@
* *
* @global string $wp_version * @global string $wp_version
*/ */
$wp_version = '5.3-alpha-45780'; $wp_version = '5.3-alpha-45781';
/** /**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.