WordPress.org
Get WordPress

Make WordPress Core

Changeset 54842


Ignore:
Timestamp:
11/15/2022 12:32:04 AM (22 months ago)
Author:
SergeyBiryukov
Message:

Docs: Minor DocBlock edits for get_adjacent_post() and related functions.

This aims to better match the line wrapping recommendations of the documentation standards.

Follow-up to [16951], [28111], [32606], [37254].

See #56792.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/link-template.php

    r54841 r54842  
    17531753 * @since 1.5.0
    17541754 *
    1755  * @param bool         $in_same_term   Optional. Whether post should be in a same taxonomy term. Default false.
    1756  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty.
    1757  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
    1758  * @return WP_Post|null|string Post object if successful. Null if global $post is not set. Empty string if no
    1759  *                             corresponding post exists.
     1755 * @param bool         $in_same_term   Optional. Whether post should be in the same taxonomy term.
     1756 *                                     Default false.
     1757 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
     1758 *                                     Default empty.
     1759 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
     1760 * @return WP_Post|null|string Post object if successful. Null if global `$post` is not set.
     1761 *                             Empty string if no corresponding post exists.
    17601762 */
    17611763function get_previous_post( $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) {
    … …  
    17681770 * @since 1.5.0
    17691771 *
    1770  * @param bool         $in_same_term   Optional. Whether post should be in a same taxonomy term. Default false.
    1771  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty.
    1772  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
    1773  * @return WP_Post|null|string Post object if successful. Null if global $post is not set. Empty string if no
    1774  *                             corresponding post exists.
     1772 * @param bool         $in_same_term   Optional. Whether post should be in the same taxonomy term.
     1773 *                                     Default false.
     1774 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
     1775 *                                     Default empty.
     1776 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
     1777 * @return WP_Post|null|string Post object if successful. Null if global `$post` is not set.
     1778 *                             Empty string if no corresponding post exists.
    17751779 */
    17761780function get_next_post( $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) {
    … …  
    17871791 * @global wpdb $wpdb WordPress database abstraction object.
    17881792 *
    1789  * @param bool         $in_same_term   Optional. Whether post should be in a same taxonomy term. Default false.
    1790  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty string.
    1791  * @param bool         $previous       Optional. Whether to retrieve previous post. Default true
    1792  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
    1793  * @return WP_Post|null|string Post object if successful. Null if global $post is not set. Empty string if no
    1794  *                             corresponding post exists.
     1793 * @param bool         $in_same_term   Optional. Whether post should be in the same taxonomy term.
     1794 *                                     Default false.
     1795 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
     1796 *                                     Default empty string.
     1797 * @param bool         $previous       Optional. Whether to retrieve previous post.
     1798 *                                     Default true.
     1799 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
     1800 * @return WP_Post|null|string Post object if successful. Null if global `$post` is not set.
     1801 *                             Empty string if no corresponding post exists.
    17951802 */
    17961803function get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previous = true, $taxonomy = 'category' ) {
    … …  
    19201927     *
    19211928     * @param string       $join           The JOIN clause in the SQL.
    1922      * @param bool         $in_same_term   Whether post should be in a same taxonomy term.
     1929     * @param bool         $in_same_term   Whether post should be in the same taxonomy term.
    19231930     * @param int[]|string $excluded_terms Array of excluded term IDs. Empty string if none were provided.
    19241931     * @param string       $taxonomy       Taxonomy. Used to identify the term used when `$in_same_term` is true.
    … …  
    19421949     *
    19431950     * @param string       $where          The `WHERE` clause in the SQL.
    1944      * @param bool         $in_same_term   Whether post should be in a same taxonomy term.
     1951     * @param bool         $in_same_term   Whether post should be in the same taxonomy term.
    19451952     * @param int[]|string $excluded_terms Array of excluded term IDs. Empty string if none were provided.
    19461953     * @param string       $taxonomy       Taxonomy. Used to identify the term used when `$in_same_term` is true.
    … …  
    20022009 *
    20032010 * @param string       $title          Optional. Link title format. Default '%title'.
    2004  * @param bool         $in_same_term   Optional. Whether link should be in a same taxonomy term. Default false.
    2005  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty.
    2006  * @param bool         $previous       Optional. Whether to display link to previous or next post. Default true.
    2007  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
     2011 * @param bool         $in_same_term   Optional. Whether link should be in the same taxonomy term.
     2012 *                                     Default false.
     2013 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
     2014 *                                     Default empty.
     2015 * @param bool         $previous       Optional. Whether to display link to previous or next post.
     2016 *                                     Default true.
     2017 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
    20082018 * @return string|void The adjacent post relational link URL.
    20092019 */
    … …  
    20662076 *
    20672077 * @param string       $title          Optional. Link title format. Default '%title'.
    2068  * @param bool         $in_same_term   Optional. Whether link should be in a same taxonomy term. Default false.
    2069  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty.
    2070  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
     2078 * @param bool         $in_same_term   Optional. Whether link should be in the same taxonomy term.
     2079 *                                     Default false.
     2080 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
     2081 *                                     Default empty.
     2082 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
    20712083 */
    20722084function adjacent_posts_rel_link( $title = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) {
    … …  
    21012113 *
    21022114 * @param string       $title          Optional. Link title format. Default '%title'.
    2103  * @param bool         $in_same_term   Optional. Whether link should be in a same taxonomy term. Default false.
    2104  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty.
    2105  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
    2106  */
    2107 function next_post_rel_link( $title = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) {
    2108     echo get_adjacent_post_rel_link( $title, $in_same_term, $excluded_terms, false, $taxonomy );
    2109 }
    2110 
    2111 /**
    2112  * Displays the relational link for the previous post adjacent to the current post.
    2113  *
    2114  * @since 2.8.0
    2115  *
    2116  * @see get_adjacent_post_rel_link()
    2117  *
    2118  * @param string       $title          Optional. Link title format. Default '%title'.
    2119  * @param bool         $in_same_term   Optional. Whether link should be in a same taxonomy term. Default false.
    2120  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default true.
    2121  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
    2122  */
    2123 function prev_post_rel_link( $title = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) {
    2124     echo get_adjacent_post_rel_link( $title, $in_same_term, $excluded_terms, true, $taxonomy );
    2125 }
    2126 
    2127 /**
    2128  * Retrieves the boundary post.
    2129  *
    2130  * Boundary being either the first or last post by publish date within the constraints specified
    2131  * by $in_same_term or $excluded_terms.
    2132  *
    2133  * @since 2.8.0
    2134  *
    2135  * @param bool         $in_same_term   Optional. Whether returned post should be in a same taxonomy term.
     2115 * @param bool         $in_same_term   Optional. Whether link should be in the same taxonomy term.
    21362116 *                                     Default false.
    21372117 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
    21382118 *                                     Default empty.
    2139  * @param bool         $start          Optional. Whether to retrieve first or last post. Default true
    2140  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
    2141  * @return null|array Array containing the boundary post object if successful, null otherwise.
     2119 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
     2120 */
     2121function next_post_rel_link( $title = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) {
     2122    echo get_adjacent_post_rel_link( $title, $in_same_term, $excluded_terms, false, $taxonomy );
     2123}
     2124
     2125/**
     2126 * Displays the relational link for the previous post adjacent to the current post.
     2127 *
     2128 * @since 2.8.0
     2129 *
     2130 * @see get_adjacent_post_rel_link()
     2131 *
     2132 * @param string       $title          Optional. Link title format. Default '%title'.
     2133 * @param bool         $in_same_term   Optional. Whether link should be in the same taxonomy term.
     2134 *                                     Default false.
     2135 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
     2136 *                                     Default true.
     2137 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
     2138 */
     2139function prev_post_rel_link( $title = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) {
     2140    echo get_adjacent_post_rel_link( $title, $in_same_term, $excluded_terms, true, $taxonomy );
     2141}
     2142
     2143/**
     2144 * Retrieves the boundary post.
     2145 *
     2146 * Boundary being either the first or last post by publish date within the constraints specified
     2147 * by `$in_same_term` or `$excluded_terms`.
     2148 *
     2149 * @since 2.8.0
     2150 *
     2151 * @param bool         $in_same_term   Optional. Whether returned post should be in the same taxonomy term.
     2152 *                                     Default false.
     2153 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
     2154 *                                     Default empty.
     2155 * @param bool         $start          Optional. Whether to retrieve first or last post.
     2156 *                                     Default true.
     2157 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
     2158 * @return array|null Array containing the boundary post object if successful, null otherwise.
    21422159 */
    21432160function get_boundary_post( $in_same_term = false, $excluded_terms = '', $start = true, $taxonomy = 'category' ) {
    … …  
    21992216 * @param string       $format         Optional. Link anchor format. Default '« %link'.
    22002217 * @param string       $link           Optional. Link permalink format. Default '%title'.
    2201  * @param bool         $in_same_term   Optional. Whether link should be in a same taxonomy term. Default false.
    2202  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty.
    2203  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
     2218 * @param bool         $in_same_term   Optional. Whether link should be in the same taxonomy term.
     2219 *                                     Default false.
     2220 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
     2221 *                                     Default empty.
     2222 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
    22042223 * @return string The link URL of the previous post in relation to the current post.
    22052224 */
    … …  
    22172236 * @param string       $format         Optional. Link anchor format. Default '« %link'.
    22182237 * @param string       $link           Optional. Link permalink format. Default '%title'.
    2219  * @param bool         $in_same_term   Optional. Whether link should be in a same taxonomy term. Default false.
    2220  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty.
    2221  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
     2238 * @param bool         $in_same_term   Optional. Whether link should be in the same taxonomy term.
     2239 *                                     Default false.
     2240 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
     2241 *                                     Default empty.
     2242 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
    22222243 */
    22232244function previous_post_link( $format = '« %link', $link = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) {
    … …  
    22322253 * @param string       $format         Optional. Link anchor format. Default '« %link'.
    22332254 * @param string       $link           Optional. Link permalink format. Default '%title'.
    2234  * @param bool         $in_same_term   Optional. Whether link should be in a same taxonomy term. Default false.
    2235  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty.
    2236  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
     2255 * @param bool         $in_same_term   Optional. Whether link should be in the same taxonomy term.
     2256 *                                     Default false.
     2257 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
     2258 *                                     Default empty.
     2259 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
    22372260 * @return string The link URL of the next post in relation to the current post.
    22382261 */
    … …  
    22492272 *
    22502273 * @param string       $format         Optional. Link anchor format. Default '« %link'.
    2251  * @param string       $link           Optional. Link permalink format. Default '%title'
    2252  * @param bool         $in_same_term   Optional. Whether link should be in a same taxonomy term. Default false.
    2253  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty.
    2254  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
     2274 * @param string       $link           Optional. Link permalink format. Default '%title'.
     2275 * @param bool         $in_same_term   Optional. Whether link should be in the same taxonomy term.
     2276 *                                     Default false.
     2277 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs.
     2278 *                                     Default empty.
     2279 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
    22552280 */
    22562281function next_post_link( $format = '%link »', $link = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) {
    … …  
    22672292 * @param string       $format         Link anchor format.
    22682293 * @param string       $link           Link permalink format.
    2269  * @param bool         $in_same_term   Optional. Whether link should be in a same taxonomy term. Default false.
    2270  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded terms IDs. Default empty.
    2271  * @param bool         $previous       Optional. Whether to display link to previous or next post. Default true.
    2272  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
     2294 * @param bool         $in_same_term   Optional. Whether link should be in the same taxonomy term.
     2295 *                                     Default false.
     2296 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded terms IDs.
     2297 *                                     Default empty.
     2298 * @param bool         $previous       Optional. Whether to display link to previous or next post.
     2299 *                                     Default true.
     2300 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
    22732301 * @return string The link URL of the previous or next post in relation to the current post.
    22742302 */
    … …  
    23372365 * @param string       $format         Link anchor format.
    23382366 * @param string       $link           Link permalink format.
    2339  * @param bool         $in_same_term   Optional. Whether link should be in a same taxonomy term. Default false.
    2340  * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded category IDs. Default empty.
    2341  * @param bool         $previous       Optional. Whether to display link to previous or next post. Default true.
    2342  * @param string       $taxonomy       Optional. Taxonomy, if $in_same_term is true. Default 'category'.
     2367 * @param bool         $in_same_term   Optional. Whether link should be in the same taxonomy term.
     2368 *                                     Default false.
     2369 * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded category IDs.
     2370 *                                     Default empty.
     2371 * @param bool         $previous       Optional. Whether to display link to previous or next post.
     2372 *                                     Default true.
     2373 * @param string       $taxonomy       Optional. Taxonomy, if `$in_same_term` is true. Default 'category'.
    23432374 */
    23442375function adjacent_post_link( $format, $link, $in_same_term = false, $excluded_terms = '', $previous = true, $taxonomy = 'category' ) {
    … …  
    23542385 *
    23552386 * @param int  $pagenum Optional. Page number. Default 1.
    2356  * @param bool $escape  Optional. Whether to escape the URL for display, with esc_url(). Defaults to true.
    2357  *                      Otherwise, prepares the URL with sanitize_url().
     2387 * @param bool $escape  Optional. Whether to escape the URL for display, with esc_url().
     2388 *                      If set to false, prepares the URL with sanitize_url(). Default true.
    23582389 * @return string The link URL for the given page number.
    23592390 */
    … …  
    26842715 *     Optional. Default post navigation arguments. Default empty array.
    26852716 *
    2686  *     @type string       $prev_text          Anchor text to display in the previous post link. Default '%title'.
    2687  *     @type string       $next_text          Anchor text to display in the next post link. Default '%title'.
    2688  *     @type bool         $in_same_term       Whether link should be in a same taxonomy term. Default false.
    2689  *     @type int[]|string $excluded_terms     Array or comma-separated list of excluded term IDs. Default empty.
     2717 *     @type string       $prev_text          Anchor text to display in the previous post link.
     2718 *                                            Default '%title'.
     2719 *     @type string       $next_text          Anchor text to display in the next post link.
     2720 *                                            Default '%title'.
     2721 *     @type bool         $in_same_term       Whether link should be in the same taxonomy term.
     2722 *                                            Default false.
     2723 *     @type int[]|string $excluded_terms     Array or comma-separated list of excluded term IDs.
     2724 *                                            Default empty.
    26902725 *     @type string       $taxonomy           Taxonomy, if `$in_same_term` is true. Default 'category'.
    2691  *     @type string       $screen_reader_text Screen reader text for the nav element. Default 'Post navigation'.
     2726 *     @type string       $screen_reader_text Screen reader text for the nav element.
     2727 *                                            Default 'Post navigation'.
    26922728 *     @type string       $aria_label         ARIA label text for the nav element. Default 'Posts'.
    26932729 *     @type string       $class              Custom class for the nav element. Default 'post-navigation'.
Note: See TracChangeset for help on using the changeset viewer.