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.

Built from https://develop.svn.wordpress.org/trunk@30753


git-svn-id: http://core.svn.wordpress.org/trunk@30743 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/includes/class-wp-filesystem-direct.php

@@ -49,10 +49,11 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 	/**
 	 * Write a string to a file
 	 *
-	 * @param string $file Remote path to the file where to write the data.
+	 * @param string $file     Remote path to the file where to write the data.
 	 * @param string $contents The data to write.
-	 * @param int $mode (optional) The file permissions as octal number, usually 0644.
+	 * @param int    $mode     Optional. The file permissions as octal number, usually 0644.
-	 * @return bool False upon failure.
+	 *                         Default false.
+	 * @return bool False upon failure, true otherwise.
 	 */
 	public function put_contents( $file, $contents, $mode = false ) {
 		$fp = @fopen( $file, 'wb' );
@@ -99,9 +100,9 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 	/**
 	 * Changes file group
 	 *
-	 * @param string $file Path to the file.
+	 * @param string $file      Path to the file.
-	 * @param mixed $group A group name or number.
+	 * @param mixed  $group     A group name or number.
-	 * @param bool $recursive (optional) If set True changes file group recursively. Defaults to False.
+	 * @param bool   $recursive Optional. If set True changes file group recursively. Default false.
 	 * @return bool Returns true on success or false on failure.
 	 */
 	public function chgrp($file, $group, $recursive = false) {
@@ -123,9 +124,10 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 	/**
 	 * Changes filesystem permissions
 	 *
-	 * @param string $file Path to the file.
+	 * @param string $file      Path to the file.
-	 * @param int $mode (optional) The permissions as octal number, usually 0644 for files, 0755 for dirs.
+	 * @param int    $mode      Optional. The permissions as octal number, usually 0644 for files,
-	 * @param bool $recursive (optional) If set True changes file group recursively. Defaults to False.
+	 *                          0755 for dirs. Default false.
+	 * @param bool   $recursive Optional. If set True changes file group recursively. Default false.
 	 * @return bool Returns true on success or false on failure.
 	 */
 	public function chmod($file, $mode = false, $recursive = false) {
@@ -152,9 +154,10 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 	/**
 	 * Changes file owner
 	 *
-	 * @param string $file Path to the file.
+	 * @param string $file      Path to the file.
-	 * @param mixed $owner A user name or number.
+	 * @param mixed  $owner     A user name or number.
-	 * @param bool $recursive (optional) If set True changes file owner recursively. Defaults to False.
+	 * @param bool   $recursive Optional. If set True changes file owner recursively.
+	 *                          Default false.
 	 * @return bool Returns true on success or false on failure.
 	 */
 	public function chown($file, $owner, $recursive = false) {

wp-admin/includes/file.php

@@ -97,8 +97,8 @@ function get_home_path() {
  *
  * @since 2.6.0
  *
- * @param string $folder Full path to folder
+ * @param string $folder Optional. Full path to folder. Default empty.
- * @param int $levels (optional) Levels of folders to follow, Default: 100 (PHP Loop limit).
+ * @param int    $levels Optional. Levels of folders to follow, Default 100 (PHP Loop limit).
  * @return bool|array False on failure, Else array of files
  */
 function list_files( $folder = '', $levels = 100 ) {
@@ -137,8 +137,8 @@ function list_files( $folder = '', $levels = 100 ) {
  *
  * @since 2.6.0
  *
- * @param string $filename (optional) Filename to base the Unique file off
+ * @param string $filename Optional. Filename to base the Unique file off. Default empty.
- * @param string $dir (optional) Directory to store the file in
+ * @param string $dir      Optional. Directory to store the file in. Default empty.
  * @return string a writable filename
  */
 function wp_tempnam($filename = '', $dir = '') {
@@ -805,14 +805,18 @@ function copy_dir($from, $to, $skip_list = array() ) {
  * Initialises and connects the WordPress Filesystem Abstraction classes.
  * This function will include the chosen transport and attempt connecting.
  *
- * Plugins may add extra transports, And force WordPress to use them by returning the filename via the 'filesystem_method_file' filter.
+ * Plugins may add extra transports, And force WordPress to use them by returning
+ * the filename via the {@see 'filesystem_method_file'} filter.
  *
  * @since 2.5.0
  *
- * @param array $args (optional) Connection args, These are passed directly to the WP_Filesystem_*() classes.
+ * @param array  $args                         Optional. Connection args, These are passed directly to
- * @param string $context (optional) Context for get_filesystem_method(), See function declaration for more information.
+ *                                             the `WP_Filesystem_*()` classes. Default false.
- * @param bool $allow_relaxed_file_ownership Whether to allow Group/World writable.
+ * @param string $context                      Optional. Context for {@see get_filesystem_method()}.
- * @return null|boolean false on failure, true on success
+ *                                             Default false.
+ * @param bool   $allow_relaxed_file_ownership Optional. Whether to allow Group/World writable.
+ *                                             Default false.
+ * @return null|boolean false on failure, true on success.
  */
 function WP_Filesystem( $args = false, $context = false, $allow_relaxed_file_ownership = false ) {
 	global $wp_filesystem;

wp-admin/includes/post.php

@@ -1116,14 +1116,14 @@ function postbox_classes( $id, $page ) {
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Get a sample permalink based off of the post name.
  *
  * @since 2.5.0
  *
- * @param integer $id    Post ID or post object.
+ * @param int    $id    Post ID or post object.
- * @param string $title (optional) Title
+ * @param string $title Optional. Title. Default null.
- * @param string $name (optional) Name
+ * @param string $name  Optional. Name. Default null.
- * @return array With two entries of type string
+ * @return array Arra yith two entries of type string.
  */
 function get_sample_permalink($id, $title = null, $name = null) {
 	$post = get_post( $id );
@@ -1185,9 +1185,9 @@ function get_sample_permalink($id, $title = null, $name = null) {
  *
  * @since 2.5.0
  *
- * @param integer $id Post ID or post object.
+ * @param int    $id        Post ID or post object.
- * @param string $new_title Optional. New title.
+ * @param string $new_title Optional. New title. Default null.
- * @param string $new_slug Optional. New slug.
+ * @param string $new_slug  Optional. New slug. Default null.
  * @return string The HTML of the sample permalink slug editor.
  */
 function get_sample_permalink_html( $id, $new_title = null, $new_slug = null ) {

wp-includes/class.wp-scripts.php

@@ -47,13 +47,15 @@ class WP_Scripts extends WP_Dependencies {
 	}
 
 	/**
-	 * Prints scripts
+	 * Prints scripts.
 	 *
 	 * Prints the scripts passed to it or the print queue. Also prints all necessary dependencies.
 	 *
-	 * @param mixed $handles (optional) Scripts to be printed. (void) prints queue, (string) prints that script, (array of strings) prints those scripts.
+	 * @param mixed $handles Optional. Scripts to be printed. (void) prints queue, (string) prints
-	 * @param int $group (optional) If scripts were queued in groups prints this group number.
+	 *                       that script, (array of strings) prints those scripts. Default false.
-	 * @return array Scripts that have been printed
+	 * @param int   $group   Optional. If scripts were queued in groups prints this group number.
+	 *                       Default false.
+	 * @return array Scripts that have been printed.
 	 */
 	public function print_scripts( $handles = false, $group = false ) {
 		return $this->do_items( $handles, $group );

wp-includes/deprecated.php

@@ -1214,7 +1214,7 @@ function comments_rss() {
  *
  * @param string $username The user's username.
  * @param string $password The user's password.
- * @param string $email The user's email (optional).
+ * @param string $email    The user's email.
  * @return int The new user's ID.
  */
 function create_user($username, $password, $email) {

wp-includes/link-template.php

@@ -2587,13 +2587,14 @@ function get_shortcut_link() {
  * Retrieve the home url for the current site.
  *
  * Returns the 'home' option with the appropriate protocol, 'https' if
- * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
+ * {@see is_ssl()} and 'http' otherwise. If `$scheme` is 'http' or 'https',
- * overridden.
+ * `is_ssl()` is overridden.
  *
  * @since 3.0.0
  *
- * @param  string $path   (optional) Path relative to the home url.
+ * @param  string $path   Optional. Path relative to the home url. Default empty.
- * @param  string $scheme (optional) Scheme to give the home url context. Currently 'http', 'https', or 'relative'.
+ * @param  string $scheme Optional. Scheme to give the home url context. Accepts
+ *                        'http', 'https', or 'relative'. Default null.
  * @return string Home url link with optional path appended.
 */
 function home_url( $path = '', $scheme = null ) {
@@ -2604,15 +2605,17 @@ function home_url( $path = '', $scheme = null ) {
  * Retrieve the home url for a given site.
  *
  * Returns the 'home' option with the appropriate protocol, 'https' if
- * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
+ * {@see is_ssl()} and 'http' otherwise. If `$scheme` is 'http' or 'https',
+ * `is_ssl()` is
  * overridden.
  *
  * @since 3.0.0
  *
- * @param  int $blog_id   (optional) Blog ID. Defaults to current blog.
+ * @param  int         $blog_id     Optional. Blog ID. Default null (current blog).
- * @param  string $path   (optional) Path relative to the home url.
+ * @param  string      $path        Optional. Path relative to the home URL. Default empty.
- * @param  string $scheme (optional) Scheme to give the home url context. Currently 'http', 'https', or 'relative'.
+ * @param  string|null $orig_scheme Optional. Scheme to give the home URL context. Accepts
- * @return string Home url link with optional path appended.
+ *                                  'http', 'https', 'relative', or null. Default null.
+ * @return string Home URL link with optional path appended.
 */
 function get_home_url( $blog_id = null, $path = '', $scheme = null ) {
 	$orig_scheme = $scheme;
@@ -2671,14 +2674,16 @@ function site_url( $path = '', $scheme = null ) {
  * Retrieve the site url for a given site.
  *
  * Returns the 'site_url' option with the appropriate protocol, 'https' if
- * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
+ * {@see is_ssl()} and 'http' otherwise. If `$scheme` is 'http' or 'https',
- * overridden.
+ * `is_ssl()` is overridden.
  *
  * @since 3.0.0
  *
- * @param int $blog_id (optional) Blog ID. Defaults to current blog.
+ * @param int    $blog_id Optional. Blog ID. Default null (current site).
- * @param string $path Optional. Path relative to the site url.
+ * @param string $path    Optional. Path relative to the site url. Default empty.
- * @param string $scheme Optional. Scheme to give the site url context. Currently 'http', 'https', 'login', 'login_post', 'admin', or 'relative'.
+ * @param string $scheme  Optional. Scheme to give the site url context. Accepts
+ *                        'http', 'https', 'login', 'login_post', 'admin', or
+ *                        'relative'. Default null.
  * @return string Site url link with optional path appended.
 */
 function get_site_url( $blog_id = null, $path = '', $scheme = null ) {
@@ -2723,13 +2728,15 @@ function admin_url( $path = '', $scheme = 'admin' ) {
 }
 
 /**
- * Retrieve the url to the admin area for a given site.
+ * Retrieves the url to the admin area for a given site.
  *
  * @since 3.0.0
  *
- * @param int $blog_id (optional) Blog ID. Defaults to current blog.
+ * @param int    $blog_id Optional. Blog ID. Default null (current site).
- * @param string $path Optional path relative to the admin url.
+ * @param string $path    Optional. Path relative to the admin url. Default empty.
- * @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.
+ * @param string $scheme  Optional. The scheme to use. Accepts 'http' or 'https',
+ *                        to force those schemes. Default 'admin', which obeys
+ *                        {@see force_ssl_admin()} and {@see is_ssl()}.
  * @return string Admin url link with optional path appended.
 */
 function get_admin_url( $blog_id = null, $path = '', $scheme = 'admin' ) {
@@ -2896,16 +2903,17 @@ function network_site_url( $path = '', $scheme = null ) {
 }
 
 /**
- * Retrieve the home url for the current network.
+ * Retrieves the home url for the current network.
  *
- * Returns the home url with the appropriate protocol, 'https' if
+ * Returns the home url with the appropriate protocol, 'https' {@see is_ssl()}
- * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
+ * and 'http' otherwise. If `$scheme` is 'http' or 'https', `is_ssl()` is
  * overridden.
  *
  * @since 3.0.0
  *
- * @param  string $path   (optional) Path relative to the home url.
+ * @param  string $path   Optional. Path relative to the home url. Default empty.
- * @param  string $scheme (optional) Scheme to give the home url context. Currently 'http', 'https', or 'relative'.
+ * @param  string $scheme Optional. Scheme to give the home url context. Accepts
+ *                        'http', 'https', or 'relative'. Default null.
  * @return string Home url link with optional path appended.
 */
 function network_home_url( $path = '', $scheme = null ) {

wp-includes/meta.php

@@ -840,18 +840,18 @@ function update_meta_cache($meta_type, $object_ids) {
 }
 
 /**
- * Given a meta query, generates SQL clauses to be appended to a main query
+ * Given a meta query, generates SQL clauses to be appended to a main query.
  *
  * @since 3.2.0
  *
  * @see WP_Meta_Query
  *
- * @param array $meta_query A meta query
+ * @param array $meta_query         A meta query.
- * @param string $type Type of meta
+ * @param string $type              Type of meta.
- * @param string $primary_table
+ * @param string $primary_table     Primary database table name.
- * @param string $primary_id_column
+ * @param string $primary_id_column Primary ID column name.
- * @param object $context (optional) The main query object
+ * @param object $context           Optional. The main query object
- * @return array( 'join' => $join_sql, 'where' => $where_sql )
+ * @return array Associative array of `JOIN` and `WHERE` SQL.
  */
 function get_meta_sql( $meta_query, $type, $primary_table, $primary_id_column, $context = null ) {
 	$meta_query_obj = new WP_Meta_Query( $meta_query );

wp-includes/user.php

@@ -2015,14 +2015,14 @@ function wp_update_user($userdata) {
  * A simpler way of inserting an user into the database.
  *
  * Creates a new user with just the username, password, and email. For more
- * complex user creation use wp_insert_user() to specify more information.
+ * complex user creation use {@see wp_insert_user()} to specify more information.
  *
  * @since 2.0.0
  * @see wp_insert_user() More complete way to create a new user
  *
  * @param string $username The user's username.
  * @param string $password The user's password.
- * @param string $email The user's email (optional).
+ * @param string $email    Optional. The user's email. Default empty.
  * @return int The new user's ID.
  */
 function wp_create_user($username, $password, $email = '') {

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.1-beta2-30752';
+$wp_version = '4.1-beta2-30753';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

wp-includes/wp-db.php

@@ -735,8 +735,8 @@ class wpdb {
 	 * @since 3.1.0
 	 *
 	 * @param resource $dbh     The resource given by mysql_connect
-	 * @param string   $charset The character set (optional)
+	 * @param string   $charset Optional. The character set. Default null.
-	 * @param string   $collate The collation (optional)
+	 * @param string   $collate Optional. The collation. Default null.
 	 */
 	public function set_charset( $dbh, $charset = null, $collate = null ) {
 		if ( ! isset( $charset ) )