WordPress.org
Get WordPress

Make WordPress Core

Ticket #26253: 26253.5.diff

File 26253.5.diff, 13.0 KB (added by kpdesign, 13 years ago)

Second pass on 26253.4.diff

  • 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 retrieved RSS bloginfo for use in 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/**
    … …  
    5877 * @package WordPress
    5978 * @subpackage Feed
    6079 * @since 2.5
    61  * @uses apply_filters() Calls 'default_feed' hook on the default feed string.
    6280 *
    6381 * @return string Default feed, or for example 'rss2', 'atom', etc.
    6482 */
    6583function get_default_feed() {
    66         $default_feed = apply_filters('default_feed', 'rss2');
     84        /**
     85         * Filter the default feed type.
     86         *
     87         * @since 2.5.0
     88         *
     89         * @param string $feed_type Type of default feed. Possible values include 'rss2', 'atom'.
     90         *                          Default 'rss2'.
     91         */
     92        $default_feed = apply_filters( 'default_feed', 'rss2' );
    6793        return 'rss' == $default_feed ? 'rss2' : $default_feed;
    6894}
    6995
    … …  
    7399 * @package WordPress
    74100 * @subpackage Feed
    75101 * @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.
    78102 *
    79103 * @param string $sep Optional.How to separate the title. See wp_title() for more info.
    80104 * @return string Error message on failure or blog title on success.
    … …  
    83107        $title = wp_title($sep, false);
    84108        if ( is_wp_error( $title ) )
    85109                return $title->get_error_message();
     110        /**
     111         * Filter the blog title for a feed title.
     112         *
     113         * @since 2.2.0
     114         *
     115         * @param string $title The current RSS post title.
     116         * @param string $sep   Separator used by wp_title().
     117         */
    86118        $title = apply_filters( 'get_wp_title_rss', $title, $sep );
    87119        return $title;
    88120}
    … …  
    93125 * @package WordPress
    94126 * @subpackage Feed
    95127 * @since 2.2.0
    96  * @uses apply_filters() Calls 'wp_title_rss' on the blog title.
    97128 * @see wp_title() $sep parameter usage.
    98129 *
    99130 * @param string $sep Optional.
    100131 */
    101132function wp_title_rss( $sep = '»' ) {
     133        /**
     134         * Filter the the blog title for display of a feed title.
     135         *
     136         * @since 2.2.0
     137         *
     138         * @see get_wp_title_rss()
     139         *
     140         * @param string $wp_title The current retrieved post title.
     141         * @param string $sep      Separator used by wp_title().
     142         */
    102143        echo apply_filters( 'wp_title_rss', get_wp_title_rss( $sep ), $sep );
    103144}
    104145
    … …  
    108149 * @package WordPress
    109150 * @subpackage Feed
    110151 * @since 2.0.0
    111  * @uses apply_filters() Calls 'the_title_rss' on the post title.
    112152 *
    113153 * @return string Current post title.
    114154 */
    115155function get_the_title_rss() {
    116156        $title = get_the_title();
    117         $title = apply_filters('the_title_rss', $title);
     157        /**
     158         * Filter the post title for a feed.
     159         *
     160         * @since 1.2.1
     161         *
     162         * @param string $title The current post title.
     163         */
     164        $title = apply_filters( 'the_title_rss', $title );
    118165        return $title;
    119166}
    120167
    … …  
    136183 * @package WordPress
    137184 * @subpackage Feed
    138185 * @since 2.9.0
    139  * @uses apply_filters() Calls 'the_content_feed' on the content before processing.
    140186 * @see get_the_content()
    141187 *
    142188 * @param string $feed_type The type of feed. rss2 | atom | rss | rdf
    … …  
    146192        if ( !$feed_type )
    147193                $feed_type = get_default_feed();
    148194
    149         $content = apply_filters('the_content', get_the_content());
     195        /** This filter is documented in wp-admin/post-template.php */
     196        $content = apply_filters( 'the_content', get_the_content() );
    150197        $content = str_replace(']]>', ']]>', $content);
    151         return apply_filters('the_content_feed', $content, $feed_type);
     198        /**
     199         * Filter the post content for use in feeds.
     200         *
     201         * @since 2.9.0
     202         *
     203         * @param string $content   The current post content.
     204         * @param string $feed_type Type of feed. Possible values include 'rss2', 'atom'.
     205         *                          Default 'rss2'.
     206         */
     207        return apply_filters( 'the_content_feed', $content, $feed_type );
    152208}
    153209
    154210/**
    … …  
    157213 * @package WordPress
    158214 * @subpackage Feed
    159215 * @since 2.9.0
    160  * @uses apply_filters() Calls 'the_content_feed' on the content before processing.
    161216 * @see get_the_content()
    162217 *
    163218 * @param string $feed_type The type of feed. rss2 | atom | rss | rdf
    … …  
    172227 * @package WordPress
    173228 * @subpackage Feed
    174229 * @since 0.71
    175  * @uses apply_filters() Calls 'the_excerpt_rss' hook on the excerpt.
    176230 */
    177231function the_excerpt_rss() {
    178232        $output = get_the_excerpt();
    179         echo apply_filters('the_excerpt_rss', $output);
     233        /**
     234         * Filter the post excerpt for a feed.
     235         *
     236         * @since 1.2.1
     237         *
     238         * @param string $output The current post excerpt returned by get_the_excerpt().
     239         */
     240        echo apply_filters( 'the_excerpt_rss', $output );
    180241}
    181242
    182243/**
    … …  
    185246 * @package WordPress
    186247 * @subpackage Feed
    187248 * @since 2.3.0
    188  * @uses apply_filters() Call 'the_permalink_rss' on the post permalink
    189249 */
    190250function the_permalink_rss() {
    191         echo esc_url( apply_filters('the_permalink_rss', get_permalink() ));
     251        /**
     252         * Filter the permalink to the post for use in feeds.
     253         *
     254         * @since 2.3.0
     255         *
     256         * @param string $post_permalink The current post permalink.
     257         */
     258        echo esc_url( apply_filters( 'the_permalink_rss', get_permalink() ) );
    192259}
    193260
    194261/**
    … …  
    198265 * @return none
    199266 */
    200267function comments_link_feed() {
     268        /**
     269         * Filter the permalink to the comments for the current post.
     270         *
     271         * @since 3.6.0
     272         *
     273         * @param string $comment_permalink The current comment permalink with '#comments' appended.
     274         */
    201275        echo esc_url( apply_filters( 'comments_link_feed', get_comments_link() ) );
    202276}
    203277
    … …  
    239313 * @since 1.5.0
    240314 */
    241315function comment_link() {
     316        /**
     317         * Filter the current comment's permalink.
     318         *
     319         * @since 3.6.0
     320         *
     321         * @see get_comment_link()
     322         *
     323         * @param string $comment_permalink The current comment permalink.
     324         */
    242325        echo esc_url( apply_filters( 'comment_link', get_comment_link() ) );
    243326}
    244327
    … …  
    248331 * @package WordPress
    249332 * @subpackage Feed
    250333 * @since 2.0.0
    251  * @uses apply_filters() Calls 'comment_author_rss' hook on comment author.
    252334 * @uses get_comment_author()
    253335 *
    254336 * @return string Comment Author
    255337 */
    256338function get_comment_author_rss() {
    257         return apply_filters('comment_author_rss', get_comment_author() );
     339        /**
     340         * Filter the current comment author for use in a feed.
     341         *
     342         * @since 1.5.0
     343         *
     344         * @see get_comment_author()
     345         *
     346         * @param string $comment_author The current comment author.
     347         */
     348        return apply_filters( 'comment_author_rss', get_comment_author() );
    258349}
    259350
    260351/**
    … …  
    274365 * @package WordPress
    275366 * @subpackage Feed
    276367 * @since 1.0.0
    277  * @uses apply_filters() Calls 'comment_text_rss' filter on comment content.
    278368 * @uses get_comment_text()
    279369 */
    280370function comment_text_rss() {
    281371        $comment_text = get_comment_text();
    282         $comment_text = apply_filters('comment_text_rss', $comment_text);
     372        /**
     373         * Filter the current comment content for use in a feed.
     374         *
     375         * @since 1.5.0
     376         *
     377         * @param string $comment_text The comment content.
     378         */
     379        $comment_text = apply_filters( 'comment_text_rss', $comment_text );
    283380        echo $comment_text;
    284381}
    285382
    … …  
    293390 * @package WordPress
    294391 * @subpackage Feed
    295392 * @since 2.1.0
    296  * @uses apply_filters()
    297393 *
    298394 * @param string $type Optional, default is the type returned by get_default_feed().
    299395 * @return string All of the post categories for displaying in the feed.
    … …  
    324420                if ( 'rdf' == $type )
    325421                        $the_list .= "\t\t<dc:subject><![CDATA[$cat_name]]></dc:subject>\n";
    326422                elseif ( 'atom' == $type )
     423                        /** This filter is documented in wp-includes/feed.php */
    327424                        $the_list .= sprintf( '<category scheme="%1$s" term="%2$s" />', esc_attr( apply_filters( 'get_bloginfo_rss', get_bloginfo( 'url' ) ) ), esc_attr( $cat_name ) );
    328425                else
    329426                        $the_list .= "\t\t<category><![CDATA[" . @html_entity_decode( $cat_name, ENT_COMPAT, get_option('blog_charset') ) . "]]></category>\n";
    330427        }
    331428
    332         return apply_filters('the_category_rss', $the_list, $type);
     429        /**
     430         * Filter all of the post categories for display in a feed.
     431         *
     432         * @since 1.2.1
     433         *
     434         * @param string $the_list All of the RSS post categories.
     435         * @param string $type     Type of feed. Possible values include 'rss2', 'atom'.
     436         *                         Default 'rss2'.
     437         */
     438        return apply_filters( 'the_category_rss', $the_list, $type );
    333439}
    334440
    335441/**
    … …  
    379485 * @package WordPress
    380486 * @subpackage Template
    381487 * @since 1.5.0
    382  * @uses apply_filters() Calls 'rss_enclosure' hook on rss enclosure.
    383488 * @uses get_post_custom() To get the current post enclosure metadata.
    384489 */
    385490function rss_enclosure() {
    … …  
    395500                                $t = preg_split('/[ \t]/', trim($enclosure[2]) );
    396501                                $type = $t[0];
    397502
    398                                 echo apply_filters('rss_enclosure', '<enclosure url="' . trim(htmlspecialchars($enclosure[0])) . '" length="' . trim($enclosure[1]) . '" type="' . $type . '" />' . "\n");
     503                                /**
     504                                 * Filter the RSS enclosure HTML link tag for the current post.
     505                                 *
     506                                 * @since 2.2.0
     507                                 *
     508                                 * @param string $html_link_tag The HTML link tag with a URI and other attributes.
     509                                 */
     510                                echo apply_filters( 'rss_enclosure', '<enclosure url="' . trim(htmlspecialchars($enclosure[0])) . '" length="' . trim($enclosure[1]) . '" type="' . $type . '" />' . "\n" );
    399511                        }
    400512                }
    401513        }
    … …  
    415527 * @package WordPress
    416528 * @subpackage Template
    417529 * @since 2.2.0
    418  * @uses apply_filters() Calls 'atom_enclosure' hook on atom enclosure.
    419530 * @uses get_post_custom() To get the current post enclosure metadata.
    420531 */
    421532function atom_enclosure() {
    … …  
    426537                if ($key == 'enclosure') {
    427538                        foreach ( (array) $val as $enc ) {
    428539                                $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");
     540                                /**
     541                                 * Filter the atom enclosure HTML link tag for the current post.
     542                                 *
     543                                 * @since 2.2.0
     544                                 *
     545                                 * @param string $html_link_tag The HTML link tag with a URI and other attributes.
     546                                 */
     547                                echo apply_filters( 'atom_enclosure', '<link href="' . trim(htmlspecialchars($enclosure[0])) . '" rel="enclosure" length="' . trim($enclosure[1]) . '" type="' . trim($enclosure[2]) . '" />' . "\n" );
    430548                        }
    431549                }
    432550        }
    … …  
    488606 */
    489607function self_link() {
    490608        $host = @parse_url(home_url());
     609        /**
     610         * Filter a feed URL.
     611         *
     612         * @since 3.6.0
     613         *
     614         * @see set_url_scheme()
     615         * @see wp_unslash()
     616         *
     617         * @param string $feed_link The link for the feed with set URL scheme.
     618         */
    491619        echo esc_url( apply_filters( 'self_link', set_url_scheme( 'http://' . $host['host'] . wp_unslash( $_SERVER['REQUEST_URI'] ) ) ) );
    492620}
    493621
    … …  
    512640
    513641        $content_type = ( !empty($types[$type]) ) ? $types[$type] : 'application/octet-stream';
    514642
     643        /**
     644         * Filter a feed content type.
     645         *
     646         * @since 2.8.0
     647         *
     648         * @param string $content_type Media type indicating the type of data that a feed contains.
     649         * @param string $type         Type of feed. Possible values include 'rss2', 'atom'.
     650         *                             Default 'rss2'.
     651         */
    515652        return apply_filters( 'feed_content_type', $content_type, $type );
    516653}
    517654
    … …  
    540677        $feed->set_file_class( 'WP_SimplePie_File' );
    541678
    542679        $feed->set_feed_url( $url );
     680        /** This filter is documented in wp-includes/class-feed.php */
    543681        $feed->set_cache_duration( apply_filters( 'wp_feed_cache_transient_lifetime', 12 * HOUR_IN_SECONDS, $url ) );
     682        /**
     683         * Fires just before processing the SimplePie feed object.
     684         *
     685         * @since 3.0.0
     686         *
     687         * @param object &$feed SimplePie feed object, passed by reference.
     688         * @param mixed  $url   URL of feed to retrieve. If an array of URLs, the feeds are merged.
     689         */
    544690        do_action_ref_array( 'wp_feed_options', array( &$feed, $url ) );
    545691        $feed->init();
    546692        $feed->handle_content_type();