[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                      |  Resolution:
 Keywords:  good-first-bug needs-patch  |     Focuses:  docs
----------------------------------------+------------------------------

Comment (by birgire):

 Thanks for the patches @Jean-David and @mukesh27

 I've also seen {{{@return mixed ...}}} being used in core.

 According to

 http://docs.phpdoc.org/guides/types.html

 the primitive types in PHPDoc are: {{{string, int, float, bool, array,
 resource, null, callable}}}.

 And regarding the {{{mixed}}} keyword it says:

 > The PHPDoc Standard also describes several keywords that are not native
 to PHP but are found to be  often used or are representations of
 situations that are convenient to describe.

 > {{{mixed}}}
 > A value with this type can be literally anything; the author of the
 documentation is unable to predict which type it will be.

 I'm not sure how strict the definition of {{{mixed}}} is in core, if it
 means that it must be "literally anything", i.e. all the primitive types
 and keywords, and that the author must be unable to predict the type?

 We have the following on {{{@return}}} in the Core Handbook:

 https://make.wordpress.org/core/handbook/best-practices/inline-
 documentation-standards/php

 {{{
 @return: Should contain all possible return types, and a description for
 each. Use a period at the end.
 Note: @return void should not be used outside of the default bundled
 themes.
 }}}

 So according to this it seems we are on the right path regarding the
 patches, but it seems we need to update it with a description for each
 type.

 @mukesh27, @Jean-David What do you think?

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