Changeset 30753 for trunk/src/wp-includes/link-template.php

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.

File:

• trunk/src/wp-includes/link-template.php (modified) (5 diffs)

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

@@ -2588 +2588 @@
  *
  * Returns the 'home' option with the appropriate protocol, 'https' if
- * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
- * overridden.
+ * {@see is_ssl()} 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 $scheme (optional) Scheme to give the home url context. Currently 'http', 'https', or 'relative'.
+ * @param  string $path   Optional. Path relative to the home url. Default empty.
+ * @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.
 */
@@ -2605 +2606 @@
  *
  * 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  string $path   (optional) Path relative to the home url.
- * @param  string $scheme (optional) Scheme to give the home url context. Currently 'http', 'https', or 'relative'.
- * @return string Home url link with optional path appended.
+ * @param  int         $blog_id     Optional. Blog ID. Default null (current blog).
+ * @param  string      $path        Optional. Path relative to the home URL. Default empty.
+ * @param  string|null $orig_scheme Optional. Scheme to give the home URL context. Accepts
+ *                                  '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 ) {
@@ -2672 +2675 @@
  *
  * 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
- * overridden.
+ * {@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 string $path Optional. Path relative to the site url.
- * @param string $scheme Optional. Scheme to give the site url context. Currently 'http', 'https', 'login', 'login_post', 'admin', or 'relative'.
+ * @param int    $blog_id Optional. Blog ID. Default null (current site).
+ * @param string $path    Optional. Path relative to the site url. Default empty.
+ * @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.
 */
@@ -2724 +2729 @@
 
 /**
- * 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 string $path Optional path relative to the admin url.
- * @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 int    $blog_id Optional. Blog ID. Default null (current site).
+ * @param string $path    Optional. Path relative to the admin url. Default empty.
+ * @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.
 */
@@ -2897 +2904 @@
 
 /**
- * Retrieve the home url for the current network.
- *
- * Returns the home url with the appropriate protocol, 'https' if
- * is_ssl() and 'http' otherwise. If $scheme is 'http' or 'https', is_ssl() is
+ * Retrieves the home url for the current network.
+ *
+ * Returns the home url with the appropriate protocol, 'https' {@see is_ssl()}
+ * 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 $scheme (optional) Scheme to give the home url context. Currently 'http', 'https', or 'relative'.
+ * @param  string $path   Optional. Path relative to the home url. Default empty.
+ * @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.
 */