[wp-trac] [WordPress Trac] #45486: Docs: Correct the inline documentation for rest_sanitize_value_from_schema()

[WordPress Trac]

#45486: Docs: Correct the inline documentation for
rest_sanitize_value_from_schema()
--------------------------+----------------------------------------
 Reporter:  birgire       |      Owner:  (none)
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  General       |    Version:  4.7
 Severity:  normal        |   Keywords:  good-first-bug needs-patch
  Focuses:  docs          |
--------------------------+----------------------------------------
 According to the inline documentation for
 {{{rest_sanitize_value_from_schema()}}} it can return {{{true}}} or
 {{{WP_Error}}}:

 {{{
 * @return true|WP_Error
 }}}

 See here:

 https://core.trac.wordpress.org/browser/tags/4.9.8/src/wp-includes/rest-
 api.php#L1214

 But it looks like it can return an {{{array}}}, {{{boolean}}},
 {{{string}}}, {{{int}}} and {{{float}}}.

 See e.g.

 https://core.trac.wordpress.org/browser/tags/4.9.8/src/wp-includes/rest-
 api.php#L1236
 https://core.trac.wordpress.org/browser/tags/4.9.8/src/wp-includes/rest-
 api.php#L1268
 https://core.trac.wordpress.org/browser/tags/4.9.8/src/wp-includes/rest-
 api.php#L1291
 https://core.trac.wordpress.org/browser/tags/4.9.8/src/wp-includes/rest-
 api.php#L1260
 https://core.trac.wordpress.org/browser/tags/4.9.8/src/wp-includes/rest-
 api.php#L1264

 It would also be informative to check if {{{WP_Error}}} can really be
 returned. It's not obvious from the function's code, but could be
 implicitly returned from the other function used there. But I haven't
 checked them all, so I'm not convinced yet :-) Looking at the unit tests
 in {{{WP_Test_REST_Schema_Sanitization}}} there are no tests for
 {{{WP_Error}}}.

 So it seems that the inline documentation for {{{@return}}} is
 accidentally the same for {{{rest_sanitize_value_from_schema()}}} and
 {{{rest_validate_value_from_schema()}}}:

 https://core.trac.wordpress.org/browser/tags/4.9.8/src/wp-includes/rest-
 api.php#L1072

 So the inline documentation needs to be corrected for
 {{{rest_sanitize_value_from_schema()}}}.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/45486>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform