WordPress.org
Get WordPress

Make WordPress Core

Changeset 48197


Ignore:
Timestamp:
06/28/2020 11:47:45 AM (4 years ago)
Author:
SergeyBiryukov
Message:

Docs: Improve documentation for optional parameters per the documentation standards.

See #49572.

Location:
trunk/src
Files:
14 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/includes/ms.php

    r47848 r48197  
    6262 *
    6363 * @param int  $blog_id Site ID.
    64  * @param bool $drop    True if site's database tables should be dropped. Default is false.
     64 * @param bool $drop    True if site's database tables should be dropped. Default false.
    6565 */
    6666function wpmu_delete_blog( $blog_id, $drop = false ) {

  • trunk/src/wp-includes/bookmark.php

    r48104 r48197  
    1717 * @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
    1818 *                       an stdClass object, an associative array, or a numeric array, respectively. Default OBJECT.
    19  * @param string $filter Optional, default is 'raw'.
     19 * @param string $filter Optional. How to sanitize bookmark fields. Default 'raw'.
    2020 * @return array|object|null Type returned depends on $output value.
    2121 */

  • trunk/src/wp-includes/category-template.php

    r48104 r48197  
    7272 * @since 0.71
    7373 *
    74  * @param int $id Optional, default to current post ID. The post ID.
     74 * @param int $id Optional. The post ID. Defaults to current post ID.
    7575 * @return WP_Term[] Array of WP_Term objects, one for each category assigned to the post.
    7676 */

  • trunk/src/wp-includes/class-wp-customize-setting.php

    r48067 r48197  
    547547     * @since 3.4.0
    548548     *
    549      * @param mixed $default A default value which is used as a fallback. Default is null.
     549     * @param mixed $default A default value which is used as a fallback. Default null.
    550550     * @return mixed The default value on failure, otherwise the sanitized and validated value.
    551551     */
    … …  
    849849     * @param $root
    850850     * @param $keys
    851      * @param bool $create Default is false.
     851     * @param bool $create Default false.
    852852     * @return array|void Keys are 'root', 'node', and 'key'.
    853853     */
    … …  
    930930     * @param $root
    931931     * @param $keys
    932      * @param mixed $default A default value which is used as a fallback. Default is null.
     932     * @param mixed $default A default value which is used as a fallback. Default null.
    933933     * @return mixed The requested value or the default value.
    934934     */

  • trunk/src/wp-includes/class-wp-http-encoding.php

    r48067 r48197  
    2424     * @since 2.8.0
    2525     *
    26      * @param string $raw String to compress.
    27      * @param int $level Optional, default is 9. Compression level, 9 is highest.
    28      * @param string $supports Optional, not used. When implemented it will choose the right compression based on what the server supports.
     26     * @param string $raw      String to compress.
     27     * @param int    $level    Optional. Compression level, 9 is highest. Default 9.
     28     * @param string $supports Optional, not used. When implemented it will choose
     29     *                         the right compression based on what the server supports.
    2930     * @return string|false False on failure.
    3031     */
    … …  
    4445     *
    4546     * @param string $compressed String to decompress.
    46      * @param int $length The optional length of the compressed data.
     47     * @param int    $length    The optional length of the compressed data.
    4748     * @return string|bool False on failure.
    4849     */

  • trunk/src/wp-includes/class-wp-rewrite.php

    r48109 r48197  
    12291229     *
    12301230     * @param string $permalink_structure The permalink structure to generate rules.
    1231      * @param bool   $walk_dirs           Optional, default is false. Whether to create list of directories to walk over.
     1231     * @param bool   $walk_dirs           Optional. Whether to create list of directories to walk over.
     1232     *                                    Default false.
    12321233     * @return array
    12331234     */

  • trunk/src/wp-includes/class-wp-roles.php

    r47219 r48197  
    202202     *
    203203     * @param string $role Role name.
    204      * @param string $cap Capability name.
    205      * @param bool $grant Optional, default is true. Whether role is capable of performing capability.
     204     * @param string $cap  Capability name.
     205     * @param bool $grant  Optional. Whether role is capable of performing capability.
     206     *                     Default true.
    206207     */
    207208    public function add_cap( $role, $cap, $grant = true ) {
    … …  
    222223     *
    223224     * @param string $role Role name.
    224      * @param string $cap Capability name.
     225     * @param string $cap  Capability name.
    225226     */
    226227    public function remove_cap( $role, $cap ) {

  • trunk/src/wp-includes/deprecated.php

    r48175 r48197  
    12431243 * @see get_term_children()
    12441244 *
    1245  * @param int $id Category ID to retrieve children.
    1246  * @param string $before Optional. Prepend before category term ID.
    1247  * @param string $after Optional, default is empty string. Append after category term ID.
    1248  * @param array $visited Optional. Category Term IDs that have already been added.
     1245 * @param int    $id      Category ID to retrieve children.
     1246 * @param string $before  Optional. Prepend before category term ID. Default '/'.
     1247 * @param string $after   Optional. Append after category term ID. Default empty string.
     1248 * @param array  $visited Optional. Category Term IDs that have already been added.
     1249 *                        Default empty array.
    12491250 * @return string
    12501251 */
    … …  
    18351836 * @see wp_get_attachment_link()
    18361837 *
    1837  * @param int $id Optional. Post ID.
    1838  * @param bool $fullsize Optional, default is false. Whether to use full size image.
     1838 * @param int   $id      Optional. Post ID.
     1839 * @param bool  $fullsize Optional. Whether to use full size image. Default false.
    18391840 * @param array $max_dims Optional. Max image dimensions.
    1840  * @param bool $permalink Optional, default is false. Whether to include permalink to image.
     1841 * @param bool $permalink Optional. Whether to include permalink to image. Default false.
    18411842 * @return string
    18421843 */
    … …  
    18651866 * @see wp_get_attachment_image_src()
    18661867 *
    1867  * @param int $id Optional. Post ID.
    1868  * @param bool $fullsize Optional, default to false. Whether to have full image.
     1868 * @param int  $id      Optional. Post ID.
     1869 * @param bool $fullsize Optional. Whether to have full image. Default false.
    18691870 * @return array Icon URL and full path to file, respectively.
    18701871 */
    … …  
    19061907 * @see wp_get_attachment_image()
    19071908 *
    1908  * @param int $id Optional. Post ID.
    1909  * @param bool $fullsize Optional, default to false. Whether to have full size image.
     1909 * @param int   $id      Optional. Post ID.
     1910 * @param bool  $fullsize Optional. Whether to have full size image. Default false.
    19101911 * @param array $max_dims Optional. Dimensions of image.
    19111912 * @return string|false HTML content.
    … …  
    19621963 * @see wp_get_attachment_image()
    19631964 *
    1964  * @param int $id Optional. Post ID.
    1965  * @param bool $fullsize Optional, default to false. Whether to have full size image.
     1965 * @param int   $id      Optional. Post ID.
     1966 * @param bool  $fullsize Optional. Whether to have full size image. Default false.
    19661967 * @param array $max_dims Optional. Dimensions of image.
    19671968 * @return string|false
    … …  
    23872388 * @see add_theme_support()
    23882389 *
    2389  * @param bool $add Optional, default is true. Add or remove links. Defaults to true.
     2390 * @param bool $add Optional. Add or remove links. Default true.
    23902391 */
    23912392function automatic_feed_links( $add = true ) {
    … …  
    24062407 *
    24072408 * @param string    $field User meta field.
    2408  * @param false|int $user Optional. User ID to retrieve the field for. Default false (current user).
     2409 * @param false|int $user  Optional. User ID to retrieve the field for. Default false (current user).
    24092410 * @return string The author's field from the current author's DB object.
    24102411 */
    … …  
    26242625 * @deprecated 3.3.0
    26252626 *
    2626  * @param object|array $user The User Object or Array
    2627  * @param string $context Optional, default is 'display'. How to sanitize user fields.
    2628  * @return object|array The now sanitized User Object or Array (will be the same type as $user)
     2627 * @param object|array $user    The user object or array.
     2628 * @param string       $context Optional. How to sanitize user fields. Default 'display'.
     2629 * @return object|array The now sanitized user object or array (will be the same type as $user).
    26292630 */
    26302631function sanitize_user_object($user, $context = 'display') {
    … …  
    26612662 * @deprecated 3.3.0
    26622663 *
    2663  * @param string $title Optional. Link title format.
    2664  * @param bool $in_same_cat Optional. Whether link should be in a same category.
    2665  * @param string $excluded_categories Optional. Excluded categories IDs.
    2666  * @param bool $start Optional, default is true. Whether to display link to first or last post.
     2664 * @param string $title               Optional. Link title format. Default '%title'.
     2665 * @param bool   $in_same_cat         Optional. Whether link should be in a same category.
     2666 *                                    Default false.
     2667 * @param string $excluded_categories Optional. Excluded categories IDs. Default empty.
     2668 * @param bool   $start               Optional. Whether to display link to first or last post.
     2669 *                                    Default true.
    26672670 * @return string
    26682671 */
    … …  
    32163219 * @see wp_get_image_editor()
    32173220 *
    3218  * @param string $file Image file path.
    3219  * @param int $max_w Maximum width to resize to.
    3220  * @param int $max_h Maximum height to resize to.
    3221  * @param bool $crop Optional. Whether to crop image or resize.
    3222  * @param string $suffix Optional. File suffix.
    3223  * @param string $dest_path Optional. New image file path.
    3224  * @param int $jpeg_quality Optional, default is 90. Image quality percentage.
     3221 * @param string $file         Image file path.
     3222 * @param int    $max_w        Maximum width to resize to.
     3223 * @param int    $max_h        Maximum height to resize to.
     3224 * @param bool   $crop         Optional. Whether to crop image or resize. Default false.
     3225 * @param string $suffix       Optional. File suffix. Default null.
     3226 * @param string $dest_path    Optional. New image file path. Default null.
     3227 * @param int    $jpeg_quality Optional. Image quality percentage. Default 90.
    32253228 * @return mixed WP_Error on failure. String with new destination path.
    32263229 */

  • trunk/src/wp-includes/general-template.php

    r48110 r48197  
    12031203 * @global WP_Locale $wp_locale WordPress date and time locale object.
    12041204 *
    1205  * @param string $sep         Optional, default is '»'. How to separate the various items
    1206  *                            within the page title.
    1207  * @param bool   $display     Optional, default is true. Whether to display or retrieve title.
     1205 * @param string $sep         Optional. How to separate the various items within the page title.
     1206 *                            Default '»'.
     1207 * @param bool   $display     Optional. Whether to display or retrieve title. Default true.
    12081208 * @param string $seplocation Optional. Location of the separator ('left' or 'right').
    12091209 * @return string|null String on retrieve, null when displaying.
    … …  
    13491349 *
    13501350 * @param string $prefix  Optional. What to display before the title.
    1351  * @param bool   $display Optional, default is true. Whether to display or retrieve title.
     1351 * @param bool   $display Optional. Whether to display or retrieve title. Default true.
    13521352 * @return string|void Title when retrieving.
    13531353 */
    … …  
    13841384 *
    13851385 * @param string $prefix  Optional. What to display before the title.
    1386  * @param bool   $display Optional, default is true. Whether to display or retrieve title.
     1386 * @param bool   $display Optional. Whether to display or retrieve title. Default true.
    13871387 * @return string|void Title when retrieving, null when displaying or failure.
    13881388 */
    … …  
    14261426 *
    14271427 * @param string $prefix  Optional. What to display before the title.
    1428  * @param bool   $display Optional, default is true. Whether to display or retrieve title.
     1428 * @param bool   $display Optional. Whether to display or retrieve title. Default true.
    14291429 * @return string|void Title when retrieving.
    14301430 */
    … …  
    14431443 *
    14441444 * @param string $prefix  Optional. What to display before the title.
    1445  * @param bool   $display Optional, default is true. Whether to display or retrieve title.
     1445 * @param bool   $display Optional. Whether to display or retrieve title. Default true.
    14461446 * @return string|void Title when retrieving.
    14471447 */
    … …  
    14601460 *
    14611461 * @param string $prefix  Optional. What to display before the title.
    1462  * @param bool   $display Optional, default is true. Whether to display or retrieve title.
     1462 * @param bool   $display Optional. Whether to display or retrieve title. Default true.
    14631463 * @return string|void Title when retrieving.
    14641464 */
    … …  
    15251525 *
    15261526 * @param string $prefix  Optional. What to display before the title.
    1527  * @param bool   $display Optional, default is true. Whether to display or retrieve title.
     1527 * @param bool   $display Optional. Whether to display or retrieve title. Default true.
    15281528 * @return string|void Title when retrieving.
    15291529 */
    … …  
    17531753 * @param string $url      URL to archive.
    17541754 * @param string $text     Archive text description.
    1755  * @param string $format   Optional, default is 'html'. Can be 'link', 'option', 'html', or custom.
     1755 * @param string $format   Optional. Can be 'link', 'option', 'html', or custom. Default 'html'.
    17561756 * @param string $before   Optional. Content to prepend to the description. Default empty.
    17571757 * @param string $after    Optional. Content to append to the description. Default empty.
    … …  
    20812081 * @global array     $posts
    20822082 *
    2083  * @param bool $initial Optional, default is true. Use initial calendar names.
    2084  * @param bool $echo    Optional, default is true. Set to false for return.
     2083 * @param bool $initial Optional. Whether to use initial calendar names. Default true.
     2084 * @param bool $display Optional. Whether to display or return the calendar. Default true.
    20852085 * @return void|string Void if `$echo` argument is true, calendar HTML if `$echo` is false.
    20862086 */
    … …  
    23752375 * @param string $before Optional. Output before the date.
    23762376 * @param string $after  Optional. Output after the date.
    2377  * @param bool   $echo   Optional, default is display. Whether to echo the date or return it.
     2377 * @param bool   $echo   Optional. Whether to echo the date or return it. Default true.
    23782378 * @return string|void String if retrieving.
    23792379 */
    … …  
    24542454 * @param string $before Optional. Output before the date.
    24552455 * @param string $after  Optional. Output after the date.
    2456  * @param bool   $echo   Optional, default is display. Whether to echo the date or return it.
     2456 * @param bool   $echo   Optional. Whether to echo the date or return it. Default true.
    24572457 * @return string|void String if retrieving.
    24582458 */

  • trunk/src/wp-includes/link-template.php

    r48185 r48197  
    258258 *
    259259 * @param int|WP_Post $id        Optional. Post ID or post object. Default is the global `$post`.
    260  * @param bool        $leavename Optional, defaults to false. Whether to keep post name. Default false.
    261  * @param bool        $sample    Optional, defaults to false. Is it a sample permalink. Default false.
     260 * @param bool        $leavename Optional. Whether to keep post name. Default false.
     261 * @param bool        $sample    Optional. Is it a sample permalink. Default false.
    262262 * @return string|WP_Error The post permalink.
    263263 */

  • trunk/src/wp-includes/post-formats.php

    r47808 r48197  
    1212 * @since 3.1.0
    1313 *
    14  * @param int|object|null $post Post ID or post object. Optional, default is the current post from the loop.
     14 * @param int|object|null $post Optional. Post ID or post object. Defaults to the current post in the loop.
    1515 * @return string|false The format if successful. False otherwise.
    1616 */
    … …  
    4343 *
    4444 * @param string|array     $format Optional. The format or formats to check.
    45  * @param WP_Post|int|null $post   Optional. The post to check. If not supplied, defaults to the current post if used in the loop.
    46  * @return bool True if the post has any of the given formats (or any format, if no format specified), false otherwise.
     45 * @param WP_Post|int|null $post   Optional. The post to check. Defaults to the current post in the loop.
     46 * @return bool True if the post has any of the given formats (or any format, if no format specified),
     47 *              false otherwise.
    4748 */
    4849function has_post_format( $format = array(), $post = null ) {
    … …  
    6566 * @param int|object $post   The post for which to assign a format.
    6667 * @param string     $format A format to assign. Use an empty string or array to remove all formats from the post.
    67  * @return array|WP_Error|false WP_Error on error. Array of affected term IDs on success.
     68 * @return array|WP_Error|false Array of affected term IDs on success. WP_Error on error.
    6869 */
    6970function set_post_format( $post, $format ) {

  • trunk/src/wp-includes/post-template.php

    r48114 r48197  
    239239 *
    240240 * @param string $more_link_text Optional. Content for when there is more text.
    241  * @param bool   $strip_teaser   Optional. Strip teaser content before the more text. Default is false.
     241 * @param bool   $strip_teaser   Optional. Strip teaser content before the more text. Default false.
    242242 */
    243243function the_content( $more_link_text = null, $strip_teaser = false ) {
    … …  
    270270 *
    271271 * @param string             $more_link_text Optional. Content for when there is more text.
    272  * @param bool               $strip_teaser   Optional. Strip teaser content before the more text. Default is false.
    273  * @param WP_Post|object|int $post           Optional. WP_Post instance or Post ID/object. Default is null.
     272 * @param bool               $strip_teaser   Optional. Strip teaser content before the more text. Default false.
     273 * @param WP_Post|object|int $post           Optional. WP_Post instance or Post ID/object. Default null.
    274274 * @return string
    275275 */
    … …  
    15671567 *
    15681568 * @param int|WP_Post $id Optional. Post ID or post object.
    1569  * @param bool        $fullsize     Optional, default is false. Whether to use full size.
     1569 * @param bool        $fullsize     Optional. Whether to use full size. Default false.
    15701570 * @param bool        $deprecated   Deprecated. Not used.
    1571  * @param bool        $permalink    Optional, default is false. Whether to include permalink.
     1571 * @param bool        $permalink    Optional. Whether to include permalink. Default false.
    15721572 */
    15731573function the_attachment_link( $id = 0, $fullsize = false, $deprecated = false, $permalink = false ) {
    … …  
    15931593 *                                of width and height values in pixels (in that order).
    15941594 *                                Default 'thumbnail'.
    1595  * @param bool         $permalink Optional, Whether to add permalink to image. Default false.
     1595 * @param bool         $permalink Optional. Whether to add permalink to image. Default false.
    15961596 * @param bool         $icon      Optional. Whether the attachment is an icon. Default false.
    15971597 * @param string|false $text      Optional. Link text to use. Activated by passing a string, false otherwise.
    … …  
    18051805 *
    18061806 * @param int|object $revision Revision ID or revision object.
    1807  * @param bool       $link     Optional, default is true. Link to revisions's page?
     1807 * @param bool       $link     Optional. Whether to link to revision's page. Default true.
    18081808 * @return string|false i18n formatted datetimestamp or localized 'Current Revision'.
    18091809 */
    … …  
    18461846 *
    18471847 * @param int|object $revision Revision ID or revision object.
    1848  * @param bool       $link     Optional, default is true. Link to revisions's page?
     1848 * @param bool       $link     Optional. Whether to link to revision's page. Default true.
    18491849 * @return string|false gravatar, user, i18n formatted datetimestamp or localized 'Current Revision'.
    18501850 */

  • trunk/src/wp-includes/taxonomy.php

    r48187 r48197  
    812812 * @param string     $output   Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
    813813 *                             a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
    814  * @param string     $filter   Optional, default is raw or no WordPress defined filter will applied.
     814 * @param string     $filter   Optional. How to sanitize term fields. Default 'raw'.
    815815 * @return WP_Term|array|WP_Error|null Object of the type specified by `$output` on success. When `$output` is 'OBJECT',
    816816 *                                     a WP_Term instance is returned. If taxonomy does not exist, a WP_Error is
    … …  
    923923 * @param string     $output   Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
    924924 *                             a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
    925  * @param string     $filter   Optional, default is raw or no WordPress defined filter will applied.
     925 * @param string     $filter   Optional. How to sanitize term fields. Default 'raw'.
    926926 * @return WP_Term|array|false WP_Term instance (or array) on success. Will return false if `$taxonomy` does not exist
    927927 *                             or `$term` was not found.
    … …  
    10451045 * @param int|WP_Term $term     Term ID or object.
    10461046 * @param string      $taxonomy Optional. Taxonomy Name. Default empty.
    1047  * @param string      $context  Optional, default is display. Look at sanitize_term_field() for available options.
     1047 * @param string      $context  Optional. How to sanitize term fields. Look at sanitize_term_field() for available options.
     1048 *                              Default 'display'.
    10481049 * @return string|int|null|WP_Error Will return an empty string if $term is not an object or if $field is not set in $term.
    10491050 */

  • trunk/src/wp-includes/widgets.php

    r48121 r48197  
    664664 * @global array $wp_registered_widgets  Registered widgets.
    665665 *
    666  * @param int|string $index Optional, default is 1. Index, name or ID of dynamic sidebar.
     666 * @param int|string $index Optional. Index, name or ID of dynamic sidebar. Default 1.
    667667 * @return bool True, if widget sidebar was found and called. False if not found or not called.
    668668 */
Note: See TracChangeset for help on using the changeset viewer.