WordPress.org
Get WordPress

Make WordPress Core

Ticket #26253: 26253.6.diff

File 26253.6.diff, 12.6 KB (added by DrewAPicture, 13 years ago)

Final pass.

  • src/wp-includes/feed.php

     
    1919 * @package WordPress
    2020 * @subpackage Feed
    2121 * @since 1.5.1
    22  * @uses apply_filters() Calls 'get_bloginfo_rss' hook with two parameters.
    2322 * @see get_bloginfo() For the list of possible values to display.
    2423 *
    2524 * @param string $show See get_bloginfo() for possible values.
    … …  
    2726 */
    2827function get_bloginfo_rss($show = '') {
    2928        $info = strip_tags(get_bloginfo($show));
    30         return apply_filters('get_bloginfo_rss', convert_chars($info), $show);
     29        /**
     30         * Filter the bloginfo for use in RSS feeds.
     31         *
     32         * @since 2.2.0
     33         *
     34         * @see convert_chars()
     35         * @see get_bloginfo()
     36         *
     37         * @param string $info Converted string value of the blog information.
     38         * @param string $show The type of blog information to retrieve.
     39         */
     40        return apply_filters( 'get_bloginfo_rss', convert_chars( $info ), $show );
    3141}
    3242
    3343/**
    … …  
    4050 * @package WordPress
    4151 * @subpackage Feed
    4252 * @since 0.71
    43  * @uses apply_filters() Calls 'bloginfo_rss' hook with two parameters.
    4453 * @see get_bloginfo() For the list of possible values to display.
    4554 *
    4655 * @param string $show See get_bloginfo() for possible values.
    4756 */
    4857function bloginfo_rss($show = '') {
    49         echo apply_filters('bloginfo_rss', get_bloginfo_rss($show), $show);
     58        /**
     59         * Filter the bloginfo for display in RSS feeds.
     60         *
     61         * @since 2.1.0
     62         *
     63         * @see get_bloginfo()
     64         *
     65         * @param string $rss_container RSS container for the blog information.
     66         * @param string $show          The type of blog information to retrieve.
     67         */
     68        echo apply_filters( 'bloginfo_rss', get_bloginfo_rss( $show ), $show );
    5069}
    5170
    5271/**
    … …  
    6382 * @return string Default feed, or for example 'rss2', 'atom', etc.
    6483 */
    6584function get_default_feed() {
    66         $default_feed = apply_filters('default_feed', 'rss2');
     85        /**
     86         * Filter the default feed type.
     87         *
     88         * @since 2.5.0
     89         *
     90         * @param string $feed_type Type of default feed. Possible values include 'rss2', 'atom'.
     91         *                          Default 'rss2'.
     92         */
     93        $default_feed = apply_filters( 'default_feed', 'rss2' );
    6794        return 'rss' == $default_feed ? 'rss2' : $default_feed;
    6895}
    6996
    … …  
    73100 * @package WordPress
    74101 * @subpackage Feed
    75102 * @since 2.2.0
    76  * @uses apply_filters() Calls 'get_wp_title_rss' hook on title.
    77  * @uses wp_title() See function for $sep parameter usage.
    78103 *
    79104 * @param string $sep Optional.How to separate the title. See wp_title() for more info.
    80105 * @return string Error message on failure or blog title on success.
    … …  
    83108        $title = wp_title($sep, false);
    84109        if ( is_wp_error( $title ) )
    85110                return $title->get_error_message();
     111        /**
     112         * Filter the blog title for use as the feed title.
     113         *
     114         * @since 2.2.0
     115         *
     116         * @param string $title The current blog title.
     117         * @param string $sep   Separator used by wp_title().
     118         */
    86119        $title = apply_filters( 'get_wp_title_rss', $title, $sep );
    87120        return $title;
    88121}
    … …  
    93126 * @package WordPress
    94127 * @subpackage Feed
    95128 * @since 2.2.0
    96  * @uses apply_filters() Calls 'wp_title_rss' on the blog title.
    97129 * @see wp_title() $sep parameter usage.
    98130 *
    99131 * @param string $sep Optional.
    100132 */
    101133function wp_title_rss( $sep = '»' ) {
     134        /**
     135         * Filter the blog title for display of the feed title.
     136         *
     137         * @since 2.2.0
     138         *
     139         * @see get_wp_title_rss()
     140         *
     141         * @param string $wp_title The current blog title.
     142         * @param string $sep      Separator used by wp_title().
     143         */
    102144        echo apply_filters( 'wp_title_rss', get_wp_title_rss( $sep ), $sep );
    103145}
    104146
    … …  
    108150 * @package WordPress
    109151 * @subpackage Feed
    110152 * @since 2.0.0
    111  * @uses apply_filters() Calls 'the_title_rss' on the post title.
    112153 *
    113154 * @return string Current post title.
    114155 */
    115156function get_the_title_rss() {
    116157        $title = get_the_title();
    117         $title = apply_filters('the_title_rss', $title);
     158        /**
     159         * Filter the post title for use in a feed.
     160         *
     161         * @since 1.2.1
     162         *
     163         * @param string $title The current post title.
     164         */
     165        $title = apply_filters( 'the_title_rss', $title );
    118166        return $title;
    119167}
    120168
    … …  
    136184 * @package WordPress
    137185 * @subpackage Feed
    138186 * @since 2.9.0
    139  * @uses apply_filters() Calls 'the_content_feed' on the content before processing.
    140187 * @see get_the_content()
    141188 *
    142189 * @param string $feed_type The type of feed. rss2 | atom | rss | rdf
    … …  
    146193        if ( !$feed_type )
    147194                $feed_type = get_default_feed();
    148195
    149         $content = apply_filters('the_content', get_the_content());
     196        /** This filter is documented in wp-admin/post-template.php */
     197        $content = apply_filters( 'the_content', get_the_content() );
    150198        $content = str_replace(']]>', ']]>', $content);
    151         return apply_filters('the_content_feed', $content, $feed_type);
     199        /**
     200         * Filter the post content for use in feeds.
     201         *
     202         * @since 2.9.0
     203         *
     204         * @param string $content   The current post content.
     205         * @param string $feed_type Type of feed. Possible values include 'rss2', 'atom'.
     206         *                          Default 'rss2'.
     207         */
     208        return apply_filters( 'the_content_feed', $content, $feed_type );
    152209}
    153210
    154211/**
    … …  
    172229 * @package WordPress
    173230 * @subpackage Feed
    174231 * @since 0.71
    175  * @uses apply_filters() Calls 'the_excerpt_rss' hook on the excerpt.
    176232 */
    177233function the_excerpt_rss() {
    178234        $output = get_the_excerpt();
    179         echo apply_filters('the_excerpt_rss', $output);
     235        /**
     236         * Filter the post excerpt for a feed.
     237         *
     238         * @since 1.2.1
     239         *
     240         * @param string $output The current post excerpt.
     241         */
     242        echo apply_filters( 'the_excerpt_rss', $output );
    180243}
    181244
    182245/**
    … …  
    185248 * @package WordPress
    186249 * @subpackage Feed
    187250 * @since 2.3.0
    188  * @uses apply_filters() Call 'the_permalink_rss' on the post permalink
    189251 */
    190252function the_permalink_rss() {
    191         echo esc_url( apply_filters('the_permalink_rss', get_permalink() ));
     253        /**
     254         * Filter the permalink to the post for use in feeds.
     255         *
     256         * @since 2.3.0
     257         *
     258         * @param string $post_permalink The current post permalink.
     259         */
     260        echo esc_url( apply_filters( 'the_permalink_rss', get_permalink() ) );
    192261}
    193262
    194263/**
    … …  
    198267 * @return none
    199268 */
    200269function comments_link_feed() {
     270        /**
     271         * Filter the comments permalink for the current post.
     272         *
     273         * @since 3.6.0
     274         *
     275         * @param string $comment_permalink The current comment permalink with
     276         *                                  '#comments' appended.
     277         */
    201278        echo esc_url( apply_filters( 'comments_link_feed', get_comments_link() ) );
    202279}
    203280
    … …  
    239316 * @since 1.5.0
    240317 */
    241318function comment_link() {
     319        /**
     320         * Filter the current comment's permalink.
     321         *
     322         * @since 3.6.0
     323         *
     324         * @see get_comment_link()
     325         *
     326         * @param string $comment_permalink The current comment permalink.
     327         */
    242328        echo esc_url( apply_filters( 'comment_link', get_comment_link() ) );
    243329}
    244330
    … …  
    248334 * @package WordPress
    249335 * @subpackage Feed
    250336 * @since 2.0.0
    251  * @uses apply_filters() Calls 'comment_author_rss' hook on comment author.
    252337 * @uses get_comment_author()
    253338 *
    254339 * @return string Comment Author
    255340 */
    256341function get_comment_author_rss() {
    257         return apply_filters('comment_author_rss', get_comment_author() );
     342        /**
     343         * Filter the current comment author for use in a feed.
     344         *
     345         * @since 1.5.0
     346         *
     347         * @see get_comment_author()
     348         *
     349         * @param string $comment_author The current comment author.
     350         */
     351        return apply_filters( 'comment_author_rss', get_comment_author() );
    258352}
    259353
    260354/**
    … …  
    274368 * @package WordPress
    275369 * @subpackage Feed
    276370 * @since 1.0.0
    277  * @uses apply_filters() Calls 'comment_text_rss' filter on comment content.
    278371 * @uses get_comment_text()
    279372 */
    280373function comment_text_rss() {
    281374        $comment_text = get_comment_text();
    282         $comment_text = apply_filters('comment_text_rss', $comment_text);
     375        /**
     376         * Filter the current comment content for use in a feed.
     377         *
     378         * @since 1.5.0
     379         *
     380         * @param string $comment_text The content of the current comment.
     381         */
     382        $comment_text = apply_filters( 'comment_text_rss', $comment_text );
    283383        echo $comment_text;
    284384}
    285385
    … …  
    293393 * @package WordPress
    294394 * @subpackage Feed
    295395 * @since 2.1.0
    296  * @uses apply_filters()
    297396 *
    298397 * @param string $type Optional, default is the type returned by get_default_feed().
    299398 * @return string All of the post categories for displaying in the feed.
    … …  
    324423                if ( 'rdf' == $type )
    325424                        $the_list .= "\t\t<dc:subject><![CDATA[$cat_name]]></dc:subject>\n";
    326425                elseif ( 'atom' == $type )
     426                        /** This filter is documented in wp-includes/feed.php */
    327427                        $the_list .= sprintf( '<category scheme="%1$s" term="%2$s" />', esc_attr( apply_filters( 'get_bloginfo_rss', get_bloginfo( 'url' ) ) ), esc_attr( $cat_name ) );
    328428                else
    329429                        $the_list .= "\t\t<category><![CDATA[" . @html_entity_decode( $cat_name, ENT_COMPAT, get_option('blog_charset') ) . "]]></category>\n";
    330430        }
    331431
    332         return apply_filters('the_category_rss', $the_list, $type);
     432        /**
     433         * Filter all of the post categories for display in a feed.
     434         *
     435         * @since 1.2.1
     436         *
     437         * @param string $the_list All of the RSS post categories.
     438         * @param string $type     Type of feed. Possible values include 'rss2', 'atom'.
     439         *                         Default 'rss2'.
     440         */
     441        return apply_filters( 'the_category_rss', $the_list, $type );
    333442}
    334443
    335444/**
    … …  
    379488 * @package WordPress
    380489 * @subpackage Template
    381490 * @since 1.5.0
    382  * @uses apply_filters() Calls 'rss_enclosure' hook on rss enclosure.
    383491 * @uses get_post_custom() To get the current post enclosure metadata.
    384492 */
    385493function rss_enclosure() {
    … …  
    395503                                $t = preg_split('/[ \t]/', trim($enclosure[2]) );
    396504                                $type = $t[0];
    397505
    398                                 echo apply_filters('rss_enclosure', '<enclosure url="' . trim(htmlspecialchars($enclosure[0])) . '" length="' . trim($enclosure[1]) . '" type="' . $type . '" />' . "\n");
     506                                /**
     507                                 * Filter the RSS enclosure HTML link tag for the current post.
     508                                 *
     509                                 * @since 2.2.0
     510                                 *
     511                                 * @param string $html_link_tag The HTML link tag with a URI and other attributes.
     512                                 */
     513                                echo apply_filters( 'rss_enclosure', '<enclosure url="' . trim( htmlspecialchars( $enclosure[0] ) ) . '" length="' . trim( $enclosure[1] ) . '" type="' . $type . '" />' . "\n" );
    399514                        }
    400515                }
    401516        }
    … …  
    415530 * @package WordPress
    416531 * @subpackage Template
    417532 * @since 2.2.0
    418  * @uses apply_filters() Calls 'atom_enclosure' hook on atom enclosure.
    419533 * @uses get_post_custom() To get the current post enclosure metadata.
    420534 */
    421535function atom_enclosure() {
    … …  
    426540                if ($key == 'enclosure') {
    427541                        foreach ( (array) $val as $enc ) {
    428542                                $enclosure = explode("\n", $enc);
    429                                 echo apply_filters('atom_enclosure', '<link href="' . trim(htmlspecialchars($enclosure[0])) . '" rel="enclosure" length="' . trim($enclosure[1]) . '" type="' . trim($enclosure[2]) . '" />' . "\n");
     543                                /**
     544                                 * Filter the atom enclosure HTML link tag for the current post.
     545                                 *
     546                                 * @since 2.2.0
     547                                 *
     548                                 * @param string $html_link_tag The HTML link tag with a URI and other attributes.
     549                                 */
     550                                echo apply_filters( 'atom_enclosure', '<link href="' . trim( htmlspecialchars( $enclosure[0] ) ) . '" rel="enclosure" length="' . trim( $enclosure[1] ) . '" type="' . trim( $enclosure[2] ) . '" />' . "\n" );
    430551                        }
    431552                }
    432553        }
    … …  
    488609 */
    489610function self_link() {
    490611        $host = @parse_url(home_url());
     612        /**
     613         * Filter the current feed URL.
     614         *
     615         * @since 3.6.0
     616         *
     617         * @see set_url_scheme()
     618         * @see wp_unslash()
     619         *
     620         * @param string $feed_link The link for the feed with set URL scheme.
     621         */
    491622        echo esc_url( apply_filters( 'self_link', set_url_scheme( 'http://' . $host['host'] . wp_unslash( $_SERVER['REQUEST_URI'] ) ) ) );
    492623}
    493624
    … …  
    512643
    513644        $content_type = ( !empty($types[$type]) ) ? $types[$type] : 'application/octet-stream';
    514645
     646        /**
     647         * Filter the content type for a specific feed type.
     648         *
     649         * @since 2.8.0
     650         *
     651         * @param string $content_type Content type indicating the type of data that a feed contains.
     652         * @param string $type         Type of feed. Possible values include 'rss2', 'atom'.
     653         *                             Default 'rss2'.
     654         */
    515655        return apply_filters( 'feed_content_type', $content_type, $type );
    516656}
    517657
    … …  
    540680        $feed->set_file_class( 'WP_SimplePie_File' );
    541681
    542682        $feed->set_feed_url( $url );
     683        /** This filter is documented in wp-includes/class-feed.php */
    543684        $feed->set_cache_duration( apply_filters( 'wp_feed_cache_transient_lifetime', 12 * HOUR_IN_SECONDS, $url ) );
     685        /**
     686         * Fires just before processing the SimplePie feed object.
     687         *
     688         * @since 3.0.0
     689         *
     690         * @param object &$feed SimplePie feed object, passed by reference.
     691         * @param mixed  $url   URL of feed to retrieve. If an array of URLs, the feeds are merged.
     692         */
    544693        do_action_ref_array( 'wp_feed_options', array( &$feed, $url ) );
    545694        $feed->init();
    546695        $feed->handle_content_type();