[wp-trac] [WordPress Trac] #50585: The Return Value of esc url raw() can be more accurate in its description

[WordPress Trac]

#50585: The Return Value of esc url raw() can be more accurate in its description
--------------------------+-----------------------------
 Reporter:  stevenlinx    |       Owner:  SergeyBiryukov
     Type:  defect (bug)  |      Status:  reviewing
 Priority:  normal        |   Milestone:  5.6
Component:  Formatting    |     Version:
 Severity:  normal        |  Resolution:
 Keywords:  has-patch     |     Focuses:  docs
--------------------------+-----------------------------

Comment (by stevenlinx):

 "...is the goal to give users a level of documentation that doesn't
 require needing to look at the codebase?"
 yes

 1.)
 I would still prefer having a more descriptive inline doc for both
 esc_url() and esc_url_raw(), if possible. This primarily for DevHub and
 not source code.

 IMO (may be just me and not everyone), having only the inline doc only on
 esc_url(), but not esc_url_raw() feels unsatisfactory due to DevHub
 parameters info are parsed from the source code inline doc.

 When reading the source code file, esc_url_raw() is only a wrapper for
 esc_url() ; the code position for esc_url_raw() is only below esc_url(),
 so the reader can just scroll up.

 However, on the DevHub page, the visitors would have to load another web
 page just to get the basic parameter info.

 2.)
 Regarding another bit of Return parameter info:
 "An empty string is returned if $url specifies a protocol other than those
 in $protocols, or if $url contains an empty string."

 I assume this should be included?

 However, in patch 3, this bit of information would be dropped from both
 esc_url() and esc_url_raw().


 In patch 3, the inline doc tells people to look at esc_url() for Return
 parameter information.

 https://developer.wordpress.org/reference/functions/esc_url/

 If you visit the esc_url() DevHub page and scroll down to the comments
 section, another commenter said
 "If the URI protocol is not one of the allowed protocols, the result of
 esc_url() is an empty string." (and this commenter missed another piece
 "An empty string is returned if $url contains an empty string")

 So why does this commenter need to mention this specific bit of
 information in a comment? because the docs are unsatisfactory and
 incomplete, which further justifies that this type of info shouldn't only
 be in the source code or the comments.

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