[wp-trac] [WordPress Trac] #50519: The return doc of wp_link_pages() need to mention $echo

[WordPress Trac]

#50519: The return doc of wp_link_pages() need to mention $echo
-------------------------------+------------------------------
 Reporter:  stevenlinx         |       Owner:  (none)
     Type:  defect (bug)       |      Status:  new
 Priority:  normal             |   Milestone:  Awaiting Review
Component:  Posts, Post Types  |     Version:
 Severity:  minor              |  Resolution:
 Keywords:  has-patch close    |     Focuses:  docs
-------------------------------+------------------------------
Changes (by SergeyBiryukov):

 * keywords:  has-patch => has-patch close


Comment:

 Thanks for the patch!

 Unlike some other functions that only return the value if `echo` is false,
 `wp_link_pages()` always returns the value, regardless of the `echo`
 parameter, so the existing documentation is correct as is.

 The `echo` parameter is already mentioned there as part of the `$args`
 array. Since it does not affect the return result, I don't think it should
 be mentioned in the `@return` tag.

 At a glance, these functions only return the value if the `echo` parameter
 is false:

 * `comment_class()`
 * `get_calendar()`
 * `the_date()`
 * `the_modified_date()`
 * `the_title()`
 * `the_title_attribute()`
 * `edit_term_link()`
 * `next_posts()`
 * `previous_posts()`
 * `wp_list_bookmarks()`
 * `wp_list_categories()`
 * `wp_list_comments()`
 * `wp_list_pages()`
 * `wp_nav_menu()`
 * `wp_page_menu()`
 * `wp_get_archives()`
 * `wp_loginout()`
 * `wp_register()`
 * `get_search_form()`
 * `get_links()` (deprecated)

 These functions always return a result, regardless of the `echo` value:

 * `wp_nonce_field()`
 * `wp_referer_field()`
 * `wp_original_referer_field()`
 * `wp_dropdown_categories()`
 * `wp_dropdown_languages()`
 * `wp_dropdown_pages()`
 * `wp_dropdown_users()`
 * `wp_link_pages()`
 * `__checked_selected_helper()`
 * `timer_stop()`
 * `the_category_ID()` (deprecated)
 * `get_author_link()` (deprecated)
 * `get_category_rss_link()` (deprecated)
 * `get_author_rss_link()` (deprecated)

 A case could be made in a new ticket for bringing some consistency here
 and moving most of the functions to the former or to the latter category.

 For now, the existing documentation for `wp_link_pages()` return value is
 correct, as noted above.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/50519#comment:2>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform