Make WordPress Core

Changeset 29011


Ignore:
Timestamp:
07/07/2014 06:18:05 AM (10 years ago)
Author:
DrewAPicture
Message:

General inline documentation improvements in wp-includes/functions.php.

Final run. Fixes #26185.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/functions.php

    r28937 r29011  
    675675 *
    676676 * @since 3.2.0
    677  *
    678  * @link  http://us1.php.net/manual/en/function.http-build-query.php
     677 * @access private
     678 *
     679 * @see http://us1.php.net/manual/en/function.http-build-query.php
    679680 *
    680681 * @param array|object  $data       An array or object of data. Converted to array.
     
    31463147
    31473148/**
    3148  * Converts value to nonnegative integer.
     3149 * Convert a value to non-negative integer.
    31493150 *
    31503151 * @since 2.5.0
    31513152 *
    3152  * @param mixed $maybeint Data you wish to have converted to a nonnegative integer
    3153  * @return int An nonnegative integer
     3153 * @param mixed $maybeint Data you wish to have converted to a non-negative integer.
     3154 * @return int A non-negative integer.
    31543155 */
    31553156function absint( $maybeint ) {
     
    31583159
    31593160/**
    3160  * Marks a function as deprecated and informs when it has been used.
     3161 * Mark a function as deprecated and informs when it has been used.
    31613162 *
    31623163 * There is a hook deprecated_function_run that will be called that can be used
     
    31713172 * @access private
    31723173 *
    3173  * @param string $function The function that was called
    3174  * @param string $version The version of WordPress that deprecated the function
    3175  * @param string $replacement Optional. The function that should have been called
     3174 * @param string $function    The function that was called.
     3175 * @param string $version     The version of WordPress that deprecated the function.
     3176 * @param string $replacement Optional. The function that should have been called. Default null.
    31763177 */
    31773178function _deprecated_function( $function, $version, $replacement = null ) {
     
    32113212
    32123213/**
    3213  * Marks a file as deprecated and informs when it has been used.
     3214 * Marks a file as deprecated and inform when it has been used.
    32143215 *
    32153216 * There is a hook deprecated_file_included that will be called that can be used
     
    32243225 * @access private
    32253226 *
    3226  * @param string $file The file that was included
    3227  * @param string $version The version of WordPress that deprecated the file
    3228  * @param string $replacement Optional. The file that should have been included based on ABSPATH
    3229  * @param string $message Optional. A message regarding the change
     3227 * @param string $file        The file that was included.
     3228 * @param string $version     The version of WordPress that deprecated the file.
     3229 * @param string $replacement Optional. The file that should have been included based on ABSPATH.
     3230 *                            Default null.
     3231 * @param string $message     Optional. A message regarding the change. Default empty.
    32303232 */
    32313233function _deprecated_file( $file, $version, $replacement = null, $message = '' ) {
     
    32663268}
    32673269/**
    3268  * Marks a function argument as deprecated and informs when it has been used.
     3270 * Mark a function argument as deprecated and inform when it has been used.
    32693271 *
    32703272 * This function is to be used whenever a deprecated function argument is used.
     
    32863288 * @access private
    32873289 *
    3288  * @param string $function The function that was called
    3289  * @param string $version The version of WordPress that deprecated the argument used
    3290  * @param string $message Optional. A message regarding the change.
     3290 * @param string $function The function that was called.
     3291 * @param string $version  The version of WordPress that deprecated the argument used.
     3292 * @param string $message  Optional. A message regarding the change. Default null.
    32913293 */
    32923294function _deprecated_argument( $function, $version, $message = null ) {
     
    33263328
    33273329/**
    3328  * Marks something as being incorrectly called.
     3330 * Mark something as being incorrectly called.
    33293331 *
    33303332 * There is a hook doing_it_wrong_run that will be called that can be used
     
    33383340 *
    33393341 * @param string $function The function that was called.
    3340  * @param string $message A message explaining what has been done incorrectly.
    3341  * @param string $version The version of WordPress where the message was added.
     3342 * @param string $message  A message explaining what has been done incorrectly.
     3343 * @param string $version  The version of WordPress where the message was added.
    33423344 */
    33433345function _doing_it_wrong( $function, $message, $version ) {
     
    33793381 * @since 2.5.0
    33803382 *
    3381  * @return bool Whether the server is running lighttpd < 1.5.0
     3383 * @return bool Whether the server is running lighttpd < 1.5.0.
    33823384 */
    33833385function is_lighttpd_before_150() {
     
    33923394 * @since 2.5.0
    33933395 *
    3394  * @param string $mod e.g. mod_rewrite
    3395  * @param bool $default The default return value if the module is not found
    3396  * @return bool
     3396 * @param string $mod     The module, e.g. mod_rewrite.
     3397 * @param bool   $default Optional. The default return value if the module is not found. Default false.
     3398 * @return bool Whether the specified module is loaded.
    33973399 */
    33983400function apache_mod_loaded($mod, $default = false) {
     
    34213423 * @since 2.8.0
    34223424 *
    3423  * @return bool
     3425 * @return bool Whether IIS7 supports permalinks.
    34243426 */
    34253427function iis7_supports_permalinks() {
     
    35053507 *
    35063508 * @param  string  $url The URL
    3507  * @return boolean      True if the given URL uses https, false if not (or if the URL is not valid).
     3509 * @return bool True if the given URL uses https, false if not (or if the URL is not valid).
    35083510 */
    35093511function is_https_url( $url ) {
     
    35163518 * @since 2.6.0
    35173519 *
    3518  * @param string|bool $force Optional.
     3520 * @see force_ssl_admin()
     3521 *
     3522 * @param string|bool $force Optional Whether to force SSL login. Default null.
    35193523 * @return bool True if forced, false if not forced.
    35203524 */
     
    35283532 * @since 2.6.0
    35293533 *
    3530  * @param string|bool $force
     3534 * @param string|bool $force Optional. Whether to force SSL in admin screens. Default null.
    35313535 * @return bool True if forced, false if not forced.
    35323536 */
     
    35513555 * @since 2.6.0
    35523556 *
    3553  * @return string
     3557 * @return string The guessed URL.
    35543558 */
    35553559function wp_guess_url() {
     
    36193623 * Suspend cache invalidation.
    36203624 *
    3621  * Turns cache invalidation on and off. Useful during imports where you don't wont to do invalidations
    3622  * every time a post is inserted. Callers must be sure that what they are doing won't lead to an inconsistent
    3623  * cache when invalidation is suspended.
     3625 * Turns cache invalidation on and off. Useful during imports where you don't wont to do
     3626 * invalidations every time a post is inserted. Callers must be sure that what they are
     3627 * doing won't lead to an inconsistent cache when invalidation is suspended.
    36243628 *
    36253629 * @since 2.7.0
    36263630 *
    3627  * @param bool $suspend Whether to suspend or enable cache invalidation
    3628  * @return bool The current suspend setting
    3629  */
    3630 function wp_suspend_cache_invalidation($suspend = true) {
     3631 * @param bool $suspend Optional. Whether to suspend or enable cache invalidation. Default true.
     3632 * @return bool The current suspend setting.
     3633 */
     3634function wp_suspend_cache_invalidation( $suspend = true ) {
    36313635    global $_wp_suspend_cache_invalidation;
    36323636
     
    36373641
    36383642/**
    3639  * Whether a site is the main site of the current network.
     3643 * Determine whether a site is the main site of the current network.
    36403644 *
    36413645 * @since 3.0.0
    36423646 *
    36433647 * @param int $site_id Optional. Site ID to test. Defaults to current site.
    3644  * @return bool True if $site_id is the main site of the network, or if not running multisite.
     3648 *                     Defaults to current site.
     3649 * @return bool True if $site_id is the main site of the network, or if not
     3650 *              running Multisite.
    36453651 */
    36463652function is_main_site( $site_id = null ) {
     
    36583664
    36593665/**
    3660  * Whether a network is the main network of the multisite install.
     3666 * Determine whether a network is the main network of the Multisite install.
    36613667 *
    36623668 * @since 3.7.0
    36633669 *
    36643670 * @param int $network_id Optional. Network ID to test. Defaults to current network.
    3665  * @return bool True if $network_id is the main network, or if not running multisite.
     3671 * @return bool True if $network_id is the main network, or if not running Multisite.
    36663672 */
    36673673function is_main_network( $network_id = null ) {
     
    36953701
    36963702/**
    3697  * Whether global terms are enabled.
    3698  *
     3703 * Determine whether global terms are enabled.
    36993704 *
    37003705 * @since 3.0.0
    37013706 *
    3702  * @return bool True if multisite and global terms enabled
     3707 * @return bool True if multisite and global terms enabled.
    37033708 */
    37043709function global_terms_enabled() {
     
    37353740 * @since 2.8.0
    37363741 *
    3737  * @return float|bool
     3742 * @return float|bool Timezone GMT offset, false otherwise.
    37383743 */
    37393744function wp_timezone_override_offset() {
     
    37543759 *
    37553760 * @since 2.9.0
     3761 * @access private
    37563762 *
    37573763 * @param array $a
     
    37983804
    37993805/**
    3800  * Gives a nicely formatted list of timezone strings.
     3806 * Gives a nicely-formatted list of timezone strings.
    38013807 *
    38023808 * @since 2.9.0
    38033809 *
    3804  * @param string $selected_zone Selected Zone
     3810 * @param string $selected_zone Selected timezone.
    38053811 * @return string
    38063812 */
     
    39283934/**
    39293935 * Strip close comment and close php tags from file headers used by WP.
    3930  * See http://core.trac.wordpress.org/ticket/8497
    39313936 *
    39323937 * @since 2.8.0
    3933  *
    3934  * @param string $str
     3938 * @access private
     3939 *
     3940 * @see http://core.trac.wordpress.org/ticket/8497
     3941 *
     3942 * @param string $str Header comment to clean up.
    39353943 * @return string
    39363944 */
    3937 function _cleanup_header_comment($str) {
     3945function _cleanup_header_comment( $str ) {
    39383946    return trim(preg_replace("/\s*(?:\*\/|\?>).*/", '', $str));
    39393947}
    39403948
    39413949/**
    3942  * Permanently deletes posts, pages, attachments, and comments which have been in the trash for EMPTY_TRASH_DAYS.
     3950 * Permanently delete posts, pages, attachments, and comments which have been
     3951 * in the trash for EMPTY_TRASH_DAYS.
    39433952 *
    39443953 * @since 2.9.0
     
    39974006 *
    39984007 * @since 2.9.0
    3999  * @param string $file Path to the file
    4000  * @param array $default_headers List of headers, in the format array('HeaderKey' => 'Header Name')
    4001  * @param string $context If specified adds filter hook "extra_{$context}_headers"
     4008 * @param string $file            Path to the file.
     4009 * @param array  $default_headers List of headers, in the format array('HeaderKey' => 'Header Name').
     4010 * @param string $context         Optional. If specified adds filter hook "extra_{$context}_headers".
     4011 *                                Default empty.
    40024012 */
    40034013function get_file_data( $file, $default_headers, $context = '' ) {
     
    40474057 *
    40484058 * @since 3.0.0
     4059 *
    40494060 * @see __return_false()
    4050  * @return bool true
     4061 *
     4062 * @return bool True.
    40514063 */
    40524064function __return_true() {
     
    40604072 *
    40614073 * @since 3.0.0
     4074 *
    40624075 * @see __return_true()
    4063  * @return bool false
     4076 *
     4077 * @return bool False.
    40644078 */
    40654079function __return_false() {
     
    40734087 *
    40744088 * @since 3.0.0
    4075  * @return int 0
     4089 *
     4090 * @return int 0.
    40764091 */
    40774092function __return_zero() {
     
    40854100 *
    40864101 * @since 3.0.0
    4087  * @return array Empty array
     4102 *
     4103 * @return array Empty array.
    40884104 */
    40894105function __return_empty_array() {
     
    40974113 *
    40984114 * @since 3.4.0
    4099  * @return null
     4115 *
     4116 * @return null Null value.
    41004117 */
    41014118function __return_null() {
     
    41094126 *
    41104127 * @since 3.7.0
     4128 *
    41114129 * @see __return_null()
    4112  * @return string Empty string
     4130 *
     4131 * @return string Empty string.
    41134132 */
    41144133function __return_empty_string() {
     
    41194138 * Send a HTTP header to disable content type sniffing in browsers which support it.
    41204139 *
    4121  * @link http://blogs.msdn.com/ie/archive/2008/07/02/ie8-security-part-v-comprehensive-protection.aspx
    4122  * @link http://src.chromium.org/viewvc/chrome?view=rev&revision=6985
    4123  *
    41244140 * @since 3.0.0
    4125  * @return none
     4141 *
     4142 * @see http://blogs.msdn.com/ie/archive/2008/07/02/ie8-security-part-v-comprehensive-protection.aspx
     4143 * @see http://src.chromium.org/viewvc/chrome?view=rev&revision=6985
    41264144 */
    41274145function send_nosniff_header() {
     
    41304148
    41314149/**
    4132  * Returns a MySQL expression for selecting the week number based on the start_of_week option.
     4150 * Return a MySQL expression for selecting the week number based on the start_of_week option.
    41334151 *
    41344152 * @internal
    41354153 * @since 3.0.0
    4136  * @param string $column
    4137  * @return string
     4154 *
     4155 * @param string $column Database column.
     4156 * @return string SQL clause.
    41384157 */
    41394158function _wp_mysql_week( $column ) {
     
    41544173
    41554174/**
    4156  * Finds hierarchy loops using a callback function that maps object IDs to parent IDs.
     4175 * Find hierarchy loops using a callback function that maps object IDs to parent IDs.
    41574176 *
    41584177 * @since 3.1.0
    41594178 * @access private
    41604179 *
    4161  * @param callback $callback function that accepts ( ID, $callback_args ) and outputs parent_ID
    4162  * @param int $start The ID to start the loop check at
    4163  * @param int $start_parent the parent_ID of $start to use instead of calling $callback( $start ). Use null to always use $callback
    4164  * @param array $callback_args optional additional arguments to send to $callback
    4165  * @return array IDs of all members of loop
     4180 * @param callback $callback      Function that accepts ( ID, $callback_args ) and outputs parent_ID.
     4181 * @param int      $start         The ID to start the loop check at.
     4182 * @param int      $start_parent  The parent_ID of $start to use instead of calling $callback( $start ).
     4183 *                                Use null to always use $callback
     4184 * @param array    $callback_args Optional. Additional arguments to send to $callback.
     4185 * @return array IDs of all members of loop.
    41664186 */
    41674187function wp_find_hierarchy_loop( $callback, $start, $start_parent, $callback_args = array() ) {
     
    41754195
    41764196/**
    4177  * Uses the "The Tortoise and the Hare" algorithm to detect loops.
     4197 * Use the "The Tortoise and the Hare" algorithm to detect loops.
    41784198 *
    41794199 * For every step of the algorithm, the hare takes two steps and the tortoise one.
     
    41834203 * @access private
    41844204 *
    4185  * @param callback $callback function that accepts ( ID, callback_arg, ... ) and outputs parent_ID
    4186  * @param int $start The ID to start the loop check at
    4187  * @param array $override an array of ( ID => parent_ID, ... ) to use instead of $callback
    4188  * @param array $callback_args optional additional arguments to send to $callback
    4189  * @param bool $_return_loop Return loop members or just detect presence of loop?
    4190  *             Only set to true if you already know the given $start is part of a loop
    4191  *             (otherwise the returned array might include branches)
    4192  * @return mixed scalar ID of some arbitrary member of the loop, or array of IDs of all members of loop if $_return_loop
     4205 * @param callback $callback      Function that accepts ( ID, callback_arg, ... ) and outputs parent_ID.
     4206 * @param int      $start         The ID to start the loop check at.
     4207 * @param array    $override      Optional. An array of ( ID => parent_ID, ... ) to use instead of $callback.
     4208 *                                Default empty array.
     4209 * @param array    $callback_args Optional. Additional arguments to send to $callback. Default empty array.
     4210 * @param bool     $_return_loop  Optional. Return loop members or just detect presence of loop? Only set
     4211 *                                to true if you already know the given $start is part of a loop (otherwise
     4212 *                                the returned array might include branches). Default false.
     4213 * @return mixed Scalar ID of some arbitrary member of the loop, or array of IDs of all members of loop if
     4214 *               $_return_loop
    41934215 */
    41944216function wp_find_hierarchy_loop_tortoise_hare( $callback, $start, $override = array(), $callback_args = array(), $_return_loop = false ) {
     
    42224244 * Send a HTTP header to limit rendering of pages to same origin iframes.
    42234245 *
    4224  * @link https://developer.mozilla.org/en/the_x-frame-options_response_header
    4225  *
    42264246 * @since 3.1.3
    4227  * @return none
     4247 *
     4248 * @see https://developer.mozilla.org/en/the_x-frame-options_response_header
    42284249 */
    42294250function send_frame_options_header() {
     
    42354256 *
    42364257 * @since 3.3.0
     4258 *
    42374259 * @see wp_kses()
    42384260 * @see esc_url()
    42394261 *
    4240  * @return array Array of allowed protocols
     4262 * @return array Array of allowed protocols.
    42414263 */
    42424264function wp_allowed_protocols() {
     
    42604282
    42614283/**
    4262  * Return a comma separated string of functions that have been called to get to the current point in code.
    4263  *
    4264  * @link http://core.trac.wordpress.org/ticket/19589
     4284 * Return a comma-separated string of functions that have been called to get
     4285 * to the current point in code.
     4286 *
    42654287 * @since 3.4.0
    42664288 *
    4267  * @param string $ignore_class A class to ignore all function calls within - useful when you want to just give info about the callee
    4268  * @param int $skip_frames A number of stack frames to skip - useful for unwinding back to the source of the issue
    4269  * @param bool $pretty Whether or not you want a comma separated string or raw array returned
    4270  * @return string|array Either a string containing a reversed comma separated trace or an array of individual calls.
     4289 * @see http://core.trac.wordpress.org/ticket/19589
     4290 *
     4291 * @param string $ignore_class Optional. A class to ignore all function calls within - useful
     4292 *                             when you want to just give info about the callee. Default null.
     4293 * @param int    $skip_frames  Optional. A number of stack frames to skip - useful for unwinding
     4294 *                             back to the source of the issue. Default 0.
     4295 * @param bool   $pretty       Optional. Whether or not you want a comma separated string or raw
     4296 *                             array returned. Default true.
     4297 * @return string|array Either a string containing a reversed comma separated trace or an array
     4298 *                      of individual calls.
    42714299 */
    42724300function wp_debug_backtrace_summary( $ignore_class = null, $skip_frames = 0, $pretty = true ) {
     
    43054333
    43064334/**
    4307  * Retrieve ids that are not already present in the cache
     4335 * Retrieve ids that are not already present in the cache.
    43084336 *
    43094337 * @since 3.4.0
    4310  *
    4311  * @param array $object_ids ID list
    4312  * @param string $cache_key The cache bucket to check against
    4313  *
    4314  * @return array
     4338 * @access private
     4339 *
     4340 * @param array  $object_ids ID list.
     4341 * @param string $cache_key  The cache bucket to check against.
     4342 *
     4343 * @return array List of ids not present in the cache.
    43154344 */
    43164345function _get_non_cached_ids( $object_ids, $cache_key ) {
     
    43324361 * @access private
    43334362 *
    4334  * @return bool true|false
     4363 * @return bool true|false Whether the device is able to upload files.
    43354364 */
    43364365function _device_can_upload() {
     
    43524381 * Test if a given path is a stream URL
    43534382 *
    4354  * @param string $path The resource path or URL
    4355  * @return bool True if the path is a stream URL
     4383 * @param string $path The resource path or URL.
     4384 * @return bool True if the path is a stream URL.
    43564385 */
    43574386function wp_is_stream( $path ) {
     
    43734402 * @param  int    $year        Year number.
    43744403 * @param  string $source_date The date to filter.
    4375  * @return bool   True if valid date, false if not valid date.
     4404 * @return bool True if valid date, false if not valid date.
    43764405 */
    43774406function wp_checkdate( $month, $day, $year, $source_date ) {
     
    44114440    /**
    44124441     * Filter whether to load the authentication check.
     4442     *
     4443     * Passing a falsey value to the filter will effectively short-circuit
     4444     * loading the authentication check.
    44134445     *
    44144446     * @since 3.6.0
     
    44884520
    44894521/**
    4490  * Return RegEx body to liberally match an opening HTML tag that:
     4522 * Return RegEx body to liberally match an opening HTML tag.
     4523 *
     4524 * Matches an opening HTML tag that:
    44914525 * 1. Is self-closing or
    44924526 * 2. Has no body but has a closing tag of the same name or
    44934527 * 3. Contains a body and a closing tag of the same name
    44944528 *
    4495  * Note: this RegEx does not balance inner tags and does not attempt to produce valid HTML
     4529 * Note: this RegEx does not balance inner tags and does not attempt
     4530 * to produce valid HTML
    44964531 *
    44974532 * @since 3.6.0
    44984533 *
    4499  * @param string $tag An HTML tag name. Example: 'video'
    4500  * @return string
     4534 * @param string $tag An HTML tag name. Example: 'video'.
     4535 * @return string Tag RegEx.
    45014536 */
    45024537function get_tag_regex( $tag ) {
     
    45074542
    45084543/**
    4509  * Return a canonical form of the provided charset appropriate for passing to PHP
     4544 * Retrieve a canonical form of the provided charset appropriate for passing to PHP
    45104545 * functions such as htmlspecialchars() and charset html attributes.
    45114546 *
    4512  * @link http://core.trac.wordpress.org/ticket/23688
    45134547 * @since 3.6.0
    4514  *
    4515  * @param string A charset name
    4516  * @return string The canonical form of the charset
     4548 * @access private
     4549 *
     4550 * @see http://core.trac.wordpress.org/ticket/23688
     4551 *
     4552 * @param string $charset A charset name.
     4553 * @return string The canonical form of the charset.
    45174554 */
    45184555function _canonical_charset( $charset ) {
     
    45294566
    45304567/**
    4531  * Sets the mbstring internal encoding to a binary safe encoding when func_overload is enabled.
    4532  *
    4533  * When mbstring.func_overload is in use for multi-byte encodings, the results from strlen() and
    4534  * similar functions respect the utf8 characters, causing binary data to return incorrect lengths.
    4535  *
    4536  * This function overrides the mbstring encoding to a binary-safe encoding, and resets it to the
    4537  * users expected encoding afterwards through the `reset_mbstring_encoding` function.
    4538  *
    4539  * It is safe to recursively call this function, however each `mbstring_binary_safe_encoding()`
    4540  * call must be followed up with an equal number of `reset_mbstring_encoding()` calls.
     4568 * Set the mbstring internal encoding to a binary safe encoding when func_overload
     4569 * is enabled.
     4570 *
     4571 * When mbstring.func_overload is in use for multi-byte encodings, the results from
     4572 * strlen() and similar functions respect the utf8 characters, causing binary data
     4573 * to return incorrect lengths.
     4574 *
     4575 * This function overrides the mbstring encoding to a binary-safe encoding, and
     4576 * resets it to the users expected encoding afterwards through the
     4577 * `reset_mbstring_encoding` function.
     4578 *
     4579 * It is safe to recursively call this function, however each
     4580 * `mbstring_binary_safe_encoding()` call must be followed up with an equal number
     4581 * of `reset_mbstring_encoding()` calls.
     4582 *
     4583 * @since 3.7.0
    45414584 *
    45424585 * @see reset_mbstring_encoding()
    45434586 *
    4544  * @since 3.7.0
    4545  *
    4546  * @param bool $reset Whether to reset the encoding back to a previously-set encoding.
     4587 * @param bool $reset Optional. Whether to reset the encoding back to a previously-set encoding.
     4588 *                    Default false.
    45474589 */
    45484590function mbstring_binary_safe_encoding( $reset = false ) {
     
    45694611
    45704612/**
    4571  * Resets the mbstring internal encoding to a users previously set encoding.
     4613 * Reset the mbstring internal encoding to a users previously set encoding.
    45724614 *
    45734615 * @see mbstring_binary_safe_encoding()
     
    45804622
    45814623/**
    4582  * Alternative to filter_var( $var, FILTER_VALIDATE_BOOLEAN )
     4624 * Alternative to filter_var( $var, FILTER_VALIDATE_BOOLEAN ).
    45834625 *
    45844626 * @since 4.0.0
    45854627 *
    4586  * @param mixed $var
    4587  * @return boolean
     4628 * @param mixed $var Boolean value to validate.
     4629 * @return bool Whether the value is validated.
    45884630 */
    45894631function wp_validate_boolean( $var ) {
Note: See TracChangeset for help on using the changeset viewer.