WordPress.org
Get WordPress

Make WordPress Core

Changeset 30753


Ignore:
Timestamp:
12/06/2014 09:23:52 PM (10 years ago)
Author:
DrewAPicture
Message:

Convert various uses of (optional) in core parameter descriptions to use the style prescribed in the inline documentation standards for PHP.

The style for marking parameters optional in inline PHP docs is: @param type $var Optional. Description. Accepts. Default., where Accepts can be omitted on a case-by-case basis.

Props coffee2code.
Fixes #30591.

Location:
trunk/src
Files:
9 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/includes/class-wp-filesystem-direct.php

    r30682 r30753  
    5050     * Write a string to a file
    5151     *
    52      * @param string $file Remote path to the file where to write the data.
     52     * @param string $file     Remote path to the file where to write the data.
    5353     * @param string $contents The data to write.
    54      * @param int $mode (optional) The file permissions as octal number, usually 0644.
    55      * @return bool False upon failure.
     54     * @param int    $mode     Optional. The file permissions as octal number, usually 0644.
     55     *                         Default false.
     56     * @return bool False upon failure, true otherwise.
    5657     */
    5758    public function put_contents( $file, $contents, $mode = false ) {
    … …  
    100101     * Changes file group
    101102     *
    102      * @param string $file Path to the file.
    103      * @param mixed $group A group name or number.
    104      * @param bool $recursive (optional) If set True changes file group recursively. Defaults to False.
     103     * @param string $file      Path to the file.
     104     * @param mixed  $group    A group name or number.
     105     * @param bool   $recursive Optional. If set True changes file group recursively. Default false.
    105106     * @return bool Returns true on success or false on failure.
    106107     */
    … …  
    124125     * Changes filesystem permissions
    125126     *
    126      * @param string $file Path to the file.
    127      * @param int $mode (optional) The permissions as octal number, usually 0644 for files, 0755 for dirs.
    128      * @param bool $recursive (optional) If set True changes file group recursively. Defaults to False.
     127     * @param string $file      Path to the file.
     128     * @param int    $mode      Optional. The permissions as octal number, usually 0644 for files,
     129     *                          0755 for dirs. Default false.
     130     * @param bool   $recursive Optional. If set True changes file group recursively. Default false.
    129131     * @return bool Returns true on success or false on failure.
    130132     */
    … …  
    153155     * Changes file owner
    154156     *
    155      * @param string $file Path to the file.
    156      * @param mixed $owner A user name or number.
    157      * @param bool $recursive (optional) If set True changes file owner recursively. Defaults to False.
     157     * @param string $file      Path to the file.
     158     * @param mixed  $owner     A user name or number.
     159     * @param bool   $recursive Optional. If set True changes file owner recursively.
     160     *                          Default false.
    158161     * @return bool Returns true on success or false on failure.
    159162     */

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

    r30648 r30753  
    9898 * @since 2.6.0
    9999 *
    100  * @param string $folder Full path to folder
    101  * @param int $levels (optional) Levels of folders to follow, Default: 100 (PHP Loop limit).
     100 * @param string $folder Optional. Full path to folder. Default empty.
     101 * @param int    $levels Optional. Levels of folders to follow, Default 100 (PHP Loop limit).
    102102 * @return bool|array False on failure, Else array of files
    103103 */
    … …  
    138138 * @since 2.6.0
    139139 *
    140  * @param string $filename (optional) Filename to base the Unique file off
    141  * @param string $dir (optional) Directory to store the file in
     140 * @param string $filename Optional. Filename to base the Unique file off. Default empty.
     141 * @param string $dir      Optional. Directory to store the file in. Default empty.
    142142 * @return string a writable filename
    143143 */
    … …  
    806806 * This function will include the chosen transport and attempt connecting.
    807807 *
    808  * Plugins may add extra transports, And force WordPress to use them by returning the filename via the 'filesystem_method_file' filter.
     808 * Plugins may add extra transports, And force WordPress to use them by returning
     809 * the filename via the {@see 'filesystem_method_file'} filter.
    809810 *
    810811 * @since 2.5.0
    811812 *
    812  * @param array $args (optional) Connection args, These are passed directly to the WP_Filesystem_*() classes.
    813  * @param string $context (optional) Context for get_filesystem_method(), See function declaration for more information.
    814  * @param bool $allow_relaxed_file_ownership Whether to allow Group/World writable.
    815  * @return null|boolean false on failure, true on success
     813 * @param array  $args                         Optional. Connection args, These are passed directly to
     814 *                                             the `WP_Filesystem_*()` classes. Default false.
     815 * @param string $context                      Optional. Context for {@see get_filesystem_method()}.
     816 *                                             Default false.
     817 * @param bool   $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable.
     818 *                                             Default false.
     819 * @return null|boolean false on failure, true on success.
    816820 */
    817821function WP_Filesystem( $args = false, $context = false, $allow_relaxed_file_ownership = false ) {

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

    r30680 r30753  
    11171117
    11181118/**
    1119  * {@internal Missing Short Description}}
     1119 * Get a sample permalink based off of the post name.
    11201120 *
    11211121 * @since 2.5.0
    11221122 *
    1123  * @param integer $id    Post ID or post object.
    1124  * @param string $title (optional) Title
    1125  * @param string $name (optional) Name
    1126  * @return array With two entries of type string
     1123 * @param int    $id    Post ID or post object.
     1124 * @param string $title Optional. Title. Default null.
     1125 * @param string $name  Optional. Name. Default null.
     1126 * @return array Arra yith two entries of type string.
    11271127 */
    11281128function get_sample_permalink($id, $title = null, $name = null) {
    … …  
    11861186 * @since 2.5.0
    11871187 *
    1188  * @param integer $id Post ID or post object.
    1189  * @param string $new_title Optional. New title.
    1190  * @param string $new_slug Optional. New slug.
     1188 * @param int    $id        Post ID or post object.
     1189 * @param string $new_title Optional. New title. Default null.
     1190 * @param string $new_slug  Optional. New slug. Default null.
    11911191 * @return string The HTML of the sample permalink slug editor.
    11921192 */

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

    r30403 r30753  
    4848
    4949    /**
    50      * Prints scripts
     50     * Prints scripts.
    5151     *
    5252     * Prints the scripts passed to it or the print queue. Also prints all necessary dependencies.
    5353     *
    54      * @param mixed $handles (optional) Scripts to be printed. (void) prints queue, (string) prints that script, (array of strings) prints those scripts.
    55      * @param int $group (optional) If scripts were queued in groups prints this group number.
    56      * @return array Scripts that have been printed
     54     * @param mixed $handles Optional. Scripts to be printed. (void) prints queue, (string) prints
     55     *                       that script, (array of strings) prints those scripts. Default false.
     56     * @param int   $group   Optional. If scripts were queued in groups prints this group number.
     57     *                       Default false.
     58     * @return array Scripts that have been printed.
    5759     */
    5860    public function print_scripts( $handles = false, $group = false ) {

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

    r30695 r30753  
    12151215 * @param string $username The user's username.
    12161216 * @param string $password The user's password.
    1217  * @param string $email The user's email (optional).
     1217 * @param string $email    The user's email.
    12181218 * @return int The new user's ID.
    12191219 */

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

    r30656 r30753  
    25882588 *
    25892589 * Returns the 'home' option with the appropriate protocol, 'https' if
    2590  * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
    2591  * overridden.
     2590 * {@see is_ssl()} and 'http' otherwise. If `$scheme` is 'http' or 'https',
     2591 * `is_ssl()` is overridden.
    25922592 *
    25932593 * @since 3.0.0
    25942594 *
    2595  * @param  string $path   (optional) Path relative to the home url.
    2596  * @param  string $scheme (optional) Scheme to give the home url context. Currently 'http', 'https', or 'relative'.
     2595 * @param  string $path   Optional. Path relative to the home url. Default empty.
     2596 * @param  string $scheme Optional. Scheme to give the home url context. Accepts
     2597 *                        'http', 'https', or 'relative'. Default null.
    25972598 * @return string Home url link with optional path appended.
    25982599*/
    … …  
    26052606 *
    26062607 * Returns the 'home' option with the appropriate protocol, 'https' if
    2607  * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
     2608 * {@see is_ssl()} and 'http' otherwise. If `$scheme` is 'http' or 'https',
     2609 * `is_ssl()` is
    26082610 * overridden.
    26092611 *
    26102612 * @since 3.0.0
    26112613 *
    2612  * @param  int $blog_id   (optional) Blog ID. Defaults to current blog.
    2613  * @param  string $path   (optional) Path relative to the home url.
    2614  * @param  string $scheme (optional) Scheme to give the home url context. Currently 'http', 'https', or 'relative'.
    2615  * @return string Home url link with optional path appended.
     2614 * @param  int         $blog_id     Optional. Blog ID. Default null (current blog).
     2615 * @param  string      $path        Optional. Path relative to the home URL. Default empty.
     2616 * @param  string|null $orig_scheme Optional. Scheme to give the home URL context. Accepts
     2617 *                                  'http', 'https', 'relative', or null. Default null.
     2618 * @return string Home URL link with optional path appended.
    26162619*/
    26172620function get_home_url( $blog_id = null, $path = '', $scheme = null ) {
    … …  
    26722675 *
    26732676 * Returns the 'site_url' option with the appropriate protocol, 'https' if
    2674  * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
    2675  * overridden.
     2677 * {@see is_ssl()} and 'http' otherwise. If `$scheme` is 'http' or 'https',
     2678 * `is_ssl()` is overridden.
    26762679 *
    26772680 * @since 3.0.0
    26782681 *
    2679  * @param int $blog_id (optional) Blog ID. Defaults to current blog.
    2680  * @param string $path Optional. Path relative to the site url.
    2681  * @param string $scheme Optional. Scheme to give the site url context. Currently 'http', 'https', 'login', 'login_post', 'admin', or 'relative'.
     2682 * @param int    $blog_id Optional. Blog ID. Default null (current site).
     2683 * @param string $path    Optional. Path relative to the site url. Default empty.
     2684 * @param string $scheme  Optional. Scheme to give the site url context. Accepts
     2685 *                        'http', 'https', 'login', 'login_post', 'admin', or
     2686 *                        'relative'. Default null.
    26822687 * @return string Site url link with optional path appended.
    26832688*/
    … …  
    27242729
    27252730/**
    2726  * Retrieve the url to the admin area for a given site.
     2731 * Retrieves the url to the admin area for a given site.
    27272732 *
    27282733 * @since 3.0.0
    27292734 *
    2730  * @param int $blog_id (optional) Blog ID. Defaults to current blog.
    2731  * @param string $path Optional path relative to the admin url.
    2732  * @param string $scheme The scheme to use. Default is 'admin', which obeys force_ssl_admin() and is_ssl(). 'http' or 'https' can be passed to force those schemes.
     2735 * @param int    $blog_id Optional. Blog ID. Default null (current site).
     2736 * @param string $path    Optional. Path relative to the admin url. Default empty.
     2737 * @param string $scheme  Optional. The scheme to use. Accepts 'http' or 'https',
     2738 *                        to force those schemes. Default 'admin', which obeys
     2739 *                        {@see force_ssl_admin()} and {@see is_ssl()}.
    27332740 * @return string Admin url link with optional path appended.
    27342741*/
    … …  
    28972904
    28982905/**
    2899  * Retrieve the home url for the current network.
    2900  *
    2901  * Returns the home url with the appropriate protocol, 'https' if
    2902  * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
     2906 * Retrieves the home url for the current network.
     2907 *
     2908 * Returns the home url with the appropriate protocol, 'https' {@see is_ssl()}
     2909 * and 'http' otherwise. If `$scheme` is 'http' or 'https', `is_ssl()` is
    29032910 * overridden.
    29042911 *
    29052912 * @since 3.0.0
    29062913 *
    2907  * @param  string $path   (optional) Path relative to the home url.
    2908  * @param  string $scheme (optional) Scheme to give the home url context. Currently 'http', 'https', or 'relative'.
     2914 * @param  string $path   Optional. Path relative to the home url. Default empty.
     2915 * @param  string $scheme Optional. Scheme to give the home url context. Accepts
     2916 *                        'http', 'https', or 'relative'. Default null.
    29092917 * @return string Home url link with optional path appended.
    29102918*/

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

    r30701 r30753  
    841841
    842842/**
    843  * Given a meta query, generates SQL clauses to be appended to a main query
     843 * Given a meta query, generates SQL clauses to be appended to a main query.
    844844 *
    845845 * @since 3.2.0
    … …  
    847847 * @see WP_Meta_Query
    848848 *
    849  * @param array $meta_query A meta query
    850  * @param string $type Type of meta
    851  * @param string $primary_table
    852  * @param string $primary_id_column
    853  * @param object $context (optional) The main query object
    854  * @return array( 'join' => $join_sql, 'where' => $where_sql )
     849 * @param array $meta_query         A meta query.
     850 * @param string $type              Type of meta.
     851 * @param string $primary_table     Primary database table name.
     852 * @param string $primary_id_column Primary ID column name.
     853 * @param object $context           Optional. The main query object
     854 * @return array Associative array of `JOIN` and `WHERE` SQL.
    855855 */
    856856function get_meta_sql( $meta_query, $type, $primary_table, $primary_id_column, $context = null ) {

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

    r30666 r30753  
    20162016 *
    20172017 * Creates a new user with just the username, password, and email. For more
    2018  * complex user creation use wp_insert_user() to specify more information.
     2018 * complex user creation use {@see wp_insert_user()} to specify more information.
    20192019 *
    20202020 * @since 2.0.0
    … …  
    20232023 * @param string $username The user's username.
    20242024 * @param string $password The user's password.
    2025  * @param string $email The user's email (optional).
     2025 * @param string $email    Optional. The user's email. Default empty.
    20262026 * @return int The new user's ID.
    20272027 */

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

    r30699 r30753  
    736736     *
    737737     * @param resource $dbh     The resource given by mysql_connect
    738      * @param string   $charset The character set (optional)
    739      * @param string   $collate The collation (optional)
     738     * @param string   $charset Optional. The character set. Default null.
     739     * @param string   $collate Optional. The collation. Default null.
    740740     */
    741741    public function set_charset( $dbh, $charset = null, $collate = null ) {
Note: See TracChangeset for help on using the changeset viewer.