The return doc of wp_link_pages() need to mention $echo

[stevenlinx]

If $echo is set to true (default), echos the content and returns the formatted output in HTML. Otherwise, returns the formatted output in HTML.

[SergeyBiryukov]

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.

[stevenlinx]

Yikes! You were right. Thank you for the comment.

The patch was based on the Return values section of Codex, which seemed to be based on an older version of the code.

"If $echo is set to true (default), returns NULL and echos the content. If $echo is set to false, returns formatted output in HTML."

It seems the older version of the code returns NULL, but have changed at some point to not return NULL at all.