Make WordPress Core

Changeset 53887


Ignore:
Timestamp:
08/12/2022 09:51:10 AM (21 months ago)
Author:
audrasjb
Message:

Docs: Use third-person singular verbs for function descriptions in wp-includes/functions.php, as per docblocks standards.

See #55646.

File:
1 edited

Legend:

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

    r53886 r53887  
    99
    1010/**
    11  * Convert given MySQL date string into a different format.
     11 * Converts given MySQL date string into a different format.
    1212 *
    1313 *  - `$format` should be a PHP date format string.
     
    409409
    410410/**
    411  * Convert float number to format based on the locale.
     411 * Converts float number to format based on the locale.
    412412 *
    413413 * @since 2.3.0
     
    499499
    500500/**
    501  * Convert a duration to human readable format.
     501 * Converts a duration to human readable format.
    502502 *
    503503 * @since 5.1.0
     
    569569
    570570/**
    571  * Get the week start and end from the datetime or date string from MySQL.
     571 * Gets the week start and end from the datetime or date string from MySQL.
    572572 *
    573573 * @since 0.71
     
    615615
    616616/**
    617  * Serialize data, if needed.
     617 * Serializes data, if needed.
    618618 *
    619619 * @since 2.0.5
     
    640640
    641641/**
    642  * Unserialize data only if it was serialized.
     642 * Unserializes data only if it was serialized.
    643643 *
    644644 * @since 2.0.0
     
    656656
    657657/**
    658  * Check value to find if it was serialized.
     658 * Checks value to find if it was serialized.
    659659 *
    660660 * If $data is not a string, then returned value will always be false.
     
    728728
    729729/**
    730  * Check whether serialized data is of string type.
     730 * Checks whether serialized data is of string type.
    731731 *
    732732 * @since 2.0.5
     
    757757
    758758/**
    759  * Retrieve post title from XMLRPC XML.
     759 * Retrieves post title from XMLRPC XML.
    760760 *
    761761 * If the title element is not part of the XML, then the default post title from
     
    780780
    781781/**
    782  * Retrieve the post category or categories from XMLRPC XML.
     782 * Retrieves the post category or categories from XMLRPC XML.
    783783 *
    784784 * If the category element is not found, then the default post category will be
     
    820820
    821821/**
    822  * Use RegEx to extract URLs from arbitrary content.
     822 * Uses RegEx to extract URLs from arbitrary content.
    823823 *
    824824 * @since 3.7.0
     
    862862
    863863/**
    864  * Check content for video and audio links to add as enclosures.
     864 * Checks content for video and audio links to add as enclosures.
    865865 *
    866866 * Will not add enclosures that have already been added and will
     
    973973
    974974/**
    975  * Retrieve HTTP Headers from URL.
     975 * Retrieves HTTP Headers from URL.
    976976 *
    977977 * @since 1.5.1
     
    10211021
    10221022/**
    1023  * Build URL query based on an associative and, or indexed array.
     1023 * Builds URL query based on an associative and, or indexed array.
    10241024 *
    10251025 * This is a convenient function for easily building url queries. It sets the
     
    13171317
    13181318/**
    1319  * Set up the WordPress query.
     1319 * Sets up the WordPress query.
    13201320 *
    13211321 * @since 2.0.0
     
    13381338
    13391339/**
    1340  * Retrieve the description for the HTTP status.
     1340 * Retrieves the description for the HTTP status.
    13411341 *
    13421342 * @since 2.3.0
     
    14321432
    14331433/**
    1434  * Set HTTP status header.
     1434 * Sets HTTP status header.
    14351435 *
    14361436 * @since 2.0.0
     
    14741474
    14751475/**
    1476  * Get the header information to prevent caching.
     1476 * Gets the header information to prevent caching.
    14771477 *
    14781478 * The several different headers cover the different ways cache prevention
     
    15111511
    15121512/**
    1513  * Set the headers to prevent caching for the different browsers.
     1513 * Sets the headers to prevent caching for the different browsers.
    15141514 *
    15151515 * Different browsers support different nocache headers, so several
     
    15381538
    15391539/**
    1540  * Set the headers for caching for 10 days with JavaScript content type.
     1540 * Sets the headers for caching for 10 days with JavaScript content type.
    15411541 *
    15421542 * @since 2.1.0
     
    15511551
    15521552/**
    1553  * Retrieve the number of database queries during the WordPress execution.
     1553 * Retrieves the number of database queries during the WordPress execution.
    15541554 *
    15551555 * @since 2.0.0
     
    15651565
    15661566/**
    1567  * Whether input is yes or no.
     1567 * Determines whether input is yes or no.
    15681568 *
    15691569 * Must be 'y' to be true.
     
    15791579
    15801580/**
    1581  * Load the feed template from the use of an action hook.
     1581 * Loads the feed template from the use of an action hook.
    15821582 *
    15831583 * If the feed action does not have a hook, then the function will die with a
     
    16281628
    16291629/**
    1630  * Load the RDF RSS 0.91 Feed template.
     1630 * Loads the RDF RSS 0.91 Feed template.
    16311631 *
    16321632 * @since 2.1.0
     
    16391639
    16401640/**
    1641  * Load the RSS 1.0 Feed Template.
     1641 * Loads the RSS 1.0 Feed Template.
    16421642 *
    16431643 * @since 2.1.0
     
    16501650
    16511651/**
    1652  * Load either the RSS2 comment feed or the RSS2 posts feed.
     1652 * Loads either the RSS2 comment feed or the RSS2 posts feed.
    16531653 *
    16541654 * @since 2.1.0
     
    16671667
    16681668/**
    1669  * Load either Atom comment feed or Atom posts feed.
     1669 * Loads either Atom comment feed or Atom posts feed.
    16701670 *
    16711671 * @since 2.1.0
     
    17211721
    17221722/**
    1723  * Display the favicon.ico file content.
     1723 * Displays the favicon.ico file content.
    17241724 *
    17251725 * @since 5.4.0
     
    18381838
    18391839/**
    1840  * Retrieve URL with nonce added to URL query.
     1840 * Retrieves URL with nonce added to URL query.
    18411841 *
    18421842 * @since 2.0.4
     
    18531853
    18541854/**
    1855  * Retrieve or display nonce hidden field for forms.
     1855 * Retrieves or display nonce hidden field for forms.
    18561856 *
    18571857 * The nonce field is used to validate that the contents of the form came from
     
    18941894
    18951895/**
    1896  * Retrieve or display referer hidden field for forms.
     1896 * Retrieves or displays referer hidden field for forms.
    18971897 *
    18981898 * The referer link is the current Request URI from the server super global. The
     
    19151915
    19161916/**
    1917  * Retrieve or display original referer hidden field for forms.
     1917 * Retrieves or displays original referer hidden field for forms.
    19181918 *
    19191919 * The input name is '_wp_original_http_referer' and will be either the same
     
    19451945
    19461946/**
    1947  * Retrieve referer from '_wp_http_referer' or HTTP referer.
     1947 * Retrieves referer from '_wp_http_referer' or HTTP referer.
    19481948 *
    19491949 * If it's the same as the current request URL, will return false.
     
    19871987
    19881988/**
    1989  * Retrieve original referer that was posted, if it exists.
     1989 * Retrieves original referer that was posted, if it exists.
    19901990 *
    19911991 * @since 2.0.4
     
    20792079
    20802080/**
    2081  * Test if a given filesystem path is absolute.
     2081 * Tests if a given filesystem path is absolute.
    20822082 *
    20832083 * For example, '/foo/bar', or 'c:\windows'.
     
    21192119
    21202120/**
    2121  * Join two filesystem paths together.
     2121 * Joins two filesystem paths together.
    21222122 *
    21232123 * For example, 'give me $path relative to $base'. If the $path is absolute,
     
    21392139
    21402140/**
    2141  * Normalize a filesystem path.
     2141 * Normalizes a filesystem path.
    21422142 *
    21432143 * On windows systems, replaces backslashes with forward slashes
     
    21782178
    21792179/**
    2180  * Determine a writable directory for temporary files.
     2180 * Determines a writable directory for temporary files.
    21812181 *
    21822182 * Function's preference is the return value of sys_get_temp_dir(),
     
    22222222
    22232223/**
    2224  * Determine if a directory is writable.
     2224 * Determines if a directory is writable.
    22252225 *
    22262226 * This function is used to work around certain ACL issues in PHP primarily
     
    25052505
    25062506/**
    2507  * Get a filename that is sanitized and unique for the given directory.
     2507 * Gets a filename that is sanitized and unique for the given directory.
    25082508 *
    25092509 * If the filename is not unique, then a number will be added to the filename
     
    28302830
    28312831/**
    2832  * Create a file in the upload folder with given content.
     2832 * Creates a file in the upload folder with given content.
    28332833 *
    28342834 * If there is an error, then the key 'error' will exist with the error message.
     
    29602960
    29612961/**
    2962  * Retrieve the file type based on the extension name.
     2962 * Retrieves the file type based on the extension name.
    29632963 *
    29642964 * @since 2.5.0
     
    29992999
    30003000/**
    3001  * Retrieve the file type from the file name.
     3001 * Retrieves the file type from the file name.
    30023002 *
    30033003 * You can optionally define the mime array, if needed.
     
    30343034
    30353035/**
    3036  * Attempt to determine the real file type of a file.
     3036 * Attempts to determine the real file type of a file.
    30373037 *
    30383038 * If unable to, the file name extension will be used to determine type.
     
    33163316
    33173317/**
    3318  * Retrieve list of mime types and file extensions.
     3318 * Retrieves the list of mime types and file extensions.
    33193319 *
    33203320 * @since 3.5.0
     
    35203520
    35213521/**
    3522  * Retrieve list of allowed mime types and file extensions.
     3522 * Retrieves the list of allowed mime types and file extensions.
    35233523 *
    35243524 * @since 2.8.6
     
    35413541
    35423542    /**
    3543      * Filters list of allowed mime types and file extensions.
     3543     * Filters the list of allowed mime types and file extensions.
    35443544     *
    35453545     * @since 2.0.0
     
    35523552
    35533553/**
    3554  * Display "Are You Sure" message to confirm the action being taken.
     3554 * Displays "Are You Sure" message to confirm the action being taken.
    35553555 *
    35563556 * If the action has the nonce explain message, then it will be displayed
     
    42354235
    42364236/**
    4237  * Encode a variable into JSON, with some sanity checks.
     4237 * Encodes a variable into JSON, with some sanity checks.
    42384238 *
    42394239 * @since 4.1.0
     
    42644264
    42654265/**
    4266  * Perform sanity checks on data that shall be encoded to JSON.
     4266 * Performs sanity checks on data that shall be encoded to JSON.
    42674267 *
    42684268 * @ignore
     
    43294329
    43304330/**
    4331  * Convert a string to UTF-8, so that it can be safely encoded to JSON.
     4331 * Converts a string to UTF-8, so that it can be safely encoded to JSON.
    43324332 *
    43334333 * @ignore
     
    43784378
    43794379/**
    4380  * Send a JSON response back to an Ajax request.
     4380 * Sends a JSON response back to an Ajax request.
    43814381 *
    43824382 * @since 3.5.0
     
    44264426
    44274427/**
    4428  * Send a JSON response back to an Ajax request, indicating success.
     4428 * Sends a JSON response back to an Ajax request, indicating success.
    44294429 *
    44304430 * @since 3.5.0
     
    44474447
    44484448/**
    4449  * Send a JSON response back to an Ajax request, indicating failure.
     4449 * Sends a JSON response back to an Ajax request, indicating failure.
    44504450 *
    44514451 * If the `$data` parameter is a WP_Error object, the errors
     
    45584558
    45594559/**
    4560  * Retrieve the WordPress home page URL.
     4560 * Retrieves the WordPress home page URL.
    45614561 *
    45624562 * If the constant named 'WP_HOME' exists, then it will be used and returned
     
    45804580
    45814581/**
    4582  * Retrieve the WordPress site URL.
     4582 * Retrieves the WordPress site URL.
    45834583 *
    45844584 * If the constant named 'WP_SITEURL' is defined, then the value in that
     
    46024602
    46034603/**
    4604  * Delete the fresh site option.
     4604 * Deletes the fresh site option.
    46054605 *
    46064606 * @since 4.7.0
     
    46124612
    46134613/**
    4614  * Set the localized direction for MCE plugin.
     4614 * Sets the localized direction for MCE plugin.
    46154615 *
    46164616 * Will only set the direction to 'rtl', if the WordPress locale has
     
    46474647
    46484648/**
    4649  * Convert smiley code to the icon graphic file equivalent.
     4649 * Converts smiley code to the icon graphic file equivalent.
    46504650 *
    46514651 * You can turn off smilies, by going to the write setting screen and unchecking
     
    48534853
    48544854/**
    4855  * Extract a slice of an array, given a list of keys.
     4855 * Extracts a slice of an array, given a list of keys.
    48564856 *
    48574857 * @since 3.1.0
     
    52415241
    52425242/**
    5243  * Append the Widgets menu to the themes main menu.
     5243 * Appends the Widgets menu to the themes main menu.
    52445244 *
    52455245 * @since 2.2.0
     
    52665266
    52675267/**
    5268  * Flush all output buffers for PHP 5.2.
     5268 * Flushes all output buffers for PHP 5.2.
    52695269 *
    52705270 * Make sure all output buffers are flushed before our singletons are destroyed.
     
    52805280
    52815281/**
    5282  * Load custom DB error or display WordPress DB error.
     5282 * Loads custom DB error or display WordPress DB error.
    52835283 *
    52845284 * If a file exists in the wp-content directory named db-error.php, then it will
     
    53185318
    53195319/**
    5320  * Convert a value to non-negative integer.
     5320 * Converts a value to non-negative integer.
    53215321 *
    53225322 * @since 2.5.0
     
    53305330
    53315331/**
    5332  * Mark a function as deprecated and inform when it has been used.
     5332 * Marks a function as deprecated and inform when it has been used.
    53335333 *
    53345334 * There is a {@see 'hook deprecated_function_run'} that will be called that can be used
     
    55155515
    55165516/**
    5517  * Mark a file as deprecated and inform when it has been used.
     5517 * Marks a file as deprecated and inform when it has been used.
    55185518 *
    55195519 * There is a hook {@see 'deprecated_file_included'} that will be called that can be used
     
    56075607}
    56085608/**
    5609  * Mark a function argument as deprecated and inform when it has been used.
     5609 * Marks a function argument as deprecated and inform when it has been used.
    56105610 *
    56115611 * This function is to be used whenever a deprecated function argument is used.
     
    57715771
    57725772/**
    5773  * Mark something as being incorrectly called.
     5773 * Marks something as being incorrectly called.
    57745774 *
    57755775 * There is a hook {@see 'doing_it_wrong_run'} that will be called that can be used
     
    58575857
    58585858/**
    5859  * Is the server running earlier than 1.5.0 version of lighttpd?
     5859 * Determines whether the server is running an earlier than 1.5.0 version of lighttpd.
    58605860 *
    58615861 * @since 2.5.0
     
    58715871
    58725872/**
    5873  * Does the specified module exist in the Apache config?
     5873 * Determines whether the specified module exist in the Apache config.
    58745874 *
    58755875 * @since 2.5.0
     
    59065906
    59075907/**
    5908  * Check if IIS 7+ supports pretty permalinks.
     5908 * Checks if IIS 7+ supports pretty permalinks.
    59095909 *
    59105910 * @since 2.8.0
     
    59905990
    59915991/**
    5992  * Whether to force SSL used for the Administration Screens.
     5992 * Determines whether to force SSL used for the Administration Screens.
    59935993 *
    59945994 * @since 2.6.0
     
    60106010
    60116011/**
    6012  * Guess the URL for the site.
     6012 * Guesses the URL for the site.
    60136013 *
    60146014 * Will remove wp-admin links to retrieve only return URLs not in the wp-admin
     
    60596059
    60606060/**
    6061  * Temporarily suspend cache additions.
     6061 * Temporarily suspends cache additions.
    60626062 *
    60636063 * Stops more data being added to the cache, but still allows cache retrieval.
     
    60846084
    60856085/**
    6086  * Suspend cache invalidation.
     6086 * Suspends cache invalidation.
    60876087 *
    60886088 * Turns cache invalidation on and off. Useful during imports where you don't want to do
     
    61066106
    61076107/**
    6108  * Determine whether a site is the main site of the current network.
     6108 * Determines whether a site is the main site of the current network.
    61096109 *
    61106110 * @since 3.0.0
     
    61546154
    61556155/**
    6156  * Determine whether a network is the main network of the Multisite installation.
     6156 * Determines whether a network is the main network of the Multisite installation.
    61576157 *
    61586158 * @since 3.7.0
     
    61766176
    61776177/**
    6178  * Get the main network ID.
     6178 * Gets the main network ID.
    61796179 *
    61806180 * @since 4.3.0
     
    62156215
    62166216/**
    6217  * Determine whether global terms are enabled.
     6217 * Determines whether global terms are enabled.
    62186218 *
    62196219 * @since 3.0.0
     
    62826282
    62836283/**
    6284  * gmt_offset modification for smart timezone handling.
     6284 * Modifies gmt_offset for smart timezone handling.
    62856285 *
    62866286 * Overrides the gmt_offset option if we have a timezone_string available.
     
    65456545
    65466546/**
    6547  * Strip close comment and close php tags from file headers used by WP.
     6547 * Strips close comment and close php tags from file headers used by WP.
    65486548 *
    65496549 * @since 2.8.0
     
    65606560
    65616561/**
    6562  * Permanently delete comments or posts of any type that have held a status
     6562 * Permanently deletes comments or posts of any type that have held a status
    65636563 * of 'trash' for the number of days defined in EMPTY_TRASH_DAYS.
    65646564 *
     
    66126612
    66136613/**
    6614  * Retrieve metadata from a file.
     6614 * Retrieves metadata from a file.
    66156615 *
    66166616 * Searches for metadata in the first 8 KB of a file, such as a plugin or theme.
     
    67566756
    67576757/**
    6758  * Send a HTTP header to disable content type sniffing in browsers which support it.
     6758 * Sends a HTTP header to disable content type sniffing in browsers which support it.
    67596759 *
    67606760 * @since 3.0.0
     
    67686768
    67696769/**
    6770  * Return a MySQL expression for selecting the week number based on the start_of_week option.
     6770 * Returns a MySQL expression for selecting the week number based on the start_of_week option.
    67716771 *
    67726772 * @ignore
     
    67946794
    67956795/**
    6796  * Find hierarchy loops using a callback function that maps object IDs to parent IDs.
     6796 * Finds hierarchy loops using a callback function that maps object IDs to parent IDs.
    67976797 *
    67986798 * @since 3.1.0
     
    68186818
    68196819/**
    6820  * Use the "The Tortoise and the Hare" algorithm to detect loops.
     6820 * Uses the "The Tortoise and the Hare" algorithm to detect loops.
    68216821 *
    68226822 * For every step of the algorithm, the hare takes two steps and the tortoise one.
     
    68716871
    68726872/**
    6873  * Send a HTTP header to limit rendering of pages to same origin iframes.
     6873 * Sends a HTTP header to limit rendering of pages to same origin iframes.
    68746874 *
    68756875 * @since 3.1.3
     
    68826882
    68836883/**
    6884  * Retrieve a list of protocols to allow in HTML attributes.
     6884 * Retrieves a list of protocols to allow in HTML attributes.
    68856885 *
    68866886 * @since 3.3.0
     
    69806980
    69816981/**
    6982  * Retrieve IDs that are not already present in the cache.
     6982 * Retrieves IDs that are not already present in the cache.
    69836983 *
    69846984 * @since 3.4.0
     
    70037003
    70047004/**
    7005  * Test if the current device has the capability to upload files.
     7005 * Tests if the current device has the capability to upload files.
    70067006 *
    70077007 * @since 3.4.0
     
    70277027
    70287028/**
    7029  * Test if a given path is a stream URL
     7029 * Tests if a given path is a stream URL
    70307030 *
    70317031 * @since 3.5.0
     
    70487048
    70497049/**
    7050  * Test if the supplied date is valid for the Gregorian calendar.
     7050 * Tests if the supplied date is valid for the Gregorian calendar.
    70517051 *
    70527052 * @since 3.5.0
     
    70737073
    70747074/**
    7075  * Load the auth check for monitoring whether the user is still logged in.
     7075 * Loads the auth check for monitoring whether the user is still logged in.
    70767076 *
    70777077 * Can be disabled with remove_action( 'admin_enqueue_scripts', 'wp_auth_check_load' );
     
    71177117
    71187118/**
    7119  * Output the HTML that shows the wp-login dialog when the user is no longer logged in.
     7119 * Outputs the HTML that shows the wp-login dialog when the user is no longer logged in.
    71207120 *
    71217121 * @since 3.6.0
     
    71687168
    71697169/**
    7170  * Check whether a user is still logged in, for the heartbeat.
     7170 * Checks whether a user is still logged in, for the heartbeat.
    71717171 *
    71727172 * Send a result that shows a log-in box if the user is no longer logged in,
     
    71867186
    71877187/**
    7188  * Return RegEx body to liberally match an opening HTML tag.
     7188 * Returns RegEx body to liberally match an opening HTML tag.
    71897189 *
    71907190 * Matches an opening HTML tag that:
     
    72097209
    72107210/**
    7211  * Retrieve a canonical form of the provided charset appropriate for passing to PHP
     7211 * Retrieves a canonical form of the provided charset appropriate for passing to PHP
    72127212 * functions such as htmlspecialchars() and charset HTML attributes.
    72137213 *
     
    72357235
    72367236/**
    7237  * Set the mbstring internal encoding to a binary safe encoding when func_overload
     7237 * Sets the mbstring internal encoding to a binary safe encoding when func_overload
    72387238 * is enabled.
    72397239 *
     
    72887288
    72897289/**
    7290  * Reset the mbstring internal encoding to a users previously set encoding.
     7290 * Resets the mbstring internal encoding to a users previously set encoding.
    72917291 *
    72927292 * @see mbstring_binary_safe_encoding()
     
    72997299
    73007300/**
    7301  * Filter/validate a variable as a boolean.
     7301 * Filters/validates a variable as a boolean.
    73027302 *
    73037303 * Alternative to `filter_var( $var, FILTER_VALIDATE_BOOLEAN )`.
     
    73217321
    73227322/**
    7323  * Delete a file
     7323 * Deletes a file.
    73247324 *
    73257325 * @since 4.2.0
     
    75387538
    75397539/**
    7540  * Generate a random UUID (version 4).
     7540 * Generates a random UUID (version 4).
    75417541 *
    75427542 * @since 4.7.0
     
    76257625
    76267626/**
    7627  * Send an email to the old site admin email address when the site admin email address changes.
     7627 * Sends an email to the old site admin email address when the site admin email address changes.
    76287628 *
    76297629 * @since 4.9.0
     
    77227722
    77237723/**
    7724  * Return an anonymized IPv4 or IPv6 address.
     7724 * Returns an anonymized IPv4 or IPv6 address.
    77257725 *
    77267726 * @since 4.9.6 Abstracted from `WP_Community_Events::get_unsafe_client_ip()`.
     
    77967796
    77977797/**
    7798  * Return uniform "anonymous" data by type.
     7798 * Returns uniform "anonymous" data by type.
    77997799 *
    78007800 * @since 4.9.6
     
    78957895
    78967896/**
    7897  * Schedule a `WP_Cron` job to delete expired export files.
     7897 * Schedules a `WP_Cron` job to delete expired export files.
    78987898 *
    78997899 * @since 4.9.6
     
    80838083
    80848084/**
    8085  * Display a button directly linking to a PHP update process.
     8085 * Displays a button directly linking to a PHP update process.
    80868086 *
    80878087 * This provides hosts with a way for users to be sent directly to their PHP update process.
     
    81958195
    81968196/**
    8197  * Get the size of a directory.
     8197 * Gets the size of a directory.
    81988198 *
    81998199 * A helper function that is used primarily to check whether
     
    82228222
    82238223/**
    8224  * Get the size of a directory recursively.
     8224 * Gets the size of a directory recursively.
    82258225 *
    82268226 * Used by get_dirsize() to get a directory size when it contains other directories.
     
    82388238 *                                            WordPress started to load.
    82398239 * @param array           $directory_cache    Optional. Array of cached directory paths.
    8240  *
    82418240 * @return int|false|null Size in bytes if a valid directory. False if not. Null if timeout.
    82428241 */
Note: See TracChangeset for help on using the changeset viewer.