sergiotarxz/Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Docs: Improve documentation for various option functions.

Browse Source 
Props andfinally, david.binda, SergeyBiryukov.
Fixes #49566.

git-svn-id: https://develop.svn.wordpress.org/trunk@48320 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Sergey Biryukov 2020-07-05 14:44:37 +00:00
parent 0df921c96d
commit fcafa02a04
2 changed files with 37 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
src/wp-includes/ms-blogs.php
View File

@ -398,7 +398,7 @@ function get_blog_option( $id, $option, $default = false ) {
* @param int $id A blog ID. Can be null to refer to the current blog. * @param int $id A blog ID. Can be null to refer to the current blog.
* @param string $option Name of option to add. Expected to not be SQL-escaped. * @param string $option Name of option to add. Expected to not be SQL-escaped.
* @param mixed $value Optional. Option value, can be anything. Expected to not be SQL-escaped. * @param mixed $value Optional. Option value, can be anything. Expected to not be SQL-escaped.
* @return bool False if option was not added and true if option was added. * @return bool True if the option was added, false otherwise.
*/ */
function add_blog_option( $id, $option, $value ) { function add_blog_option( $id, $option, $value ) {
$id = (int) $id; $id = (int) $id;
@ -425,7 +425,7 @@ function add_blog_option( $id, $option, $value ) {
* *
* @param int $id A blog ID. Can be null to refer to the current blog. * @param int $id A blog ID. Can be null to refer to the current blog.
* @param string $option Name of option to remove. Expected to not be SQL-escaped. * @param string $option Name of option to remove. Expected to not be SQL-escaped.
* @return bool True, if option is successfully deleted. False on failure. * @return bool True if the option was deleted, false otherwise.
*/ */
function delete_blog_option( $id, $option ) { function delete_blog_option( $id, $option ) {
$id = (int) $id; $id = (int) $id;
@ -454,7 +454,7 @@ function delete_blog_option( $id, $option ) {
* @param string $option The option key. * @param string $option The option key.
* @param mixed $value The option value. * @param mixed $value The option value.
* @param mixed $deprecated Not used. * @param mixed $deprecated Not used.
* @return bool True on success, false on failure. * @return bool True if the value was updated, false otherwise.
*/ */
function update_blog_option( $id, $option, $value, $deprecated = null ) { function update_blog_option( $id, $option, $value, $deprecated = null ) {
$id = (int) $id; $id = (int) $id;

66
src/wp-includes/option.php
View File

@ -23,7 +23,7 @@
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $option Name of option to retrieve. Expected to not be SQL-escaped. * @param string $option Name of the option to retrieve. Expected to not be SQL-escaped.
* @param mixed $default Optional. Default value to return if the option does not exist. * @param mixed $default Optional. Default value to return if the option does not exist.
* @return mixed Value set for the option. * @return mixed Value set for the option.
*/ */
@ -297,13 +297,13 @@ function wp_load_core_site_options( $network_id = null ) {
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $option Option name. Expected to not be SQL-escaped. * @param string $option Name of the option to update. Expected to not be SQL-escaped.
* @param mixed $value Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped. * @param mixed $value Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.
* @param string|bool $autoload Optional. Whether to load the option when WordPress starts up. For existing options, * @param string|bool $autoload Optional. Whether to load the option when WordPress starts up. For existing options,
* `$autoload` can only be updated using `update_option()` if `$value` is also changed. * `$autoload` can only be updated using `update_option()` if `$value` is also changed.
* Accepts 'yes'|true to enable or 'no'|false to disable. For non-existent options, * Accepts 'yes'|true to enable or 'no'|false to disable. For non-existent options,
* the default value is 'yes'. Default null. * the default value is 'yes'. Default null.
* @return bool False if value was not updated and true if value was updated. * @return bool True if the value was updated, false otherwise.
*/ */
function update_option( $option, $value, $autoload = null ) { function update_option( $option, $value, $autoload = null ) {
global $wpdb; global $wpdb;
@ -457,13 +457,13 @@ function update_option( $option, $value, $autoload = null ) {
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $option Name of option to add. Expected to not be SQL-escaped. * @param string $option Name of the option to add. Expected to not be SQL-escaped.
* @param mixed $value Optional. Option value. Must be serializable if non-scalar. * @param mixed $value Optional. Option value. Must be serializable if non-scalar.
* Expected to not be SQL-escaped. * Expected to not be SQL-escaped.
* @param string $deprecated Optional. Description. Not used anymore. * @param string $deprecated Optional. Description. Not used anymore.
* @param string|bool $autoload Optional. Whether to load the option when WordPress starts up. * @param string|bool $autoload Optional. Whether to load the option when WordPress starts up.
* Default is enabled. Accepts 'no' to disable for legacy reasons. * Default is enabled. Accepts 'no' to disable for legacy reasons.
* @return bool False if option was not added and true if option was added. * @return bool True if the option was added, false otherwise.
*/ */
function add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' ) { function add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' ) {
global $wpdb; global $wpdb;
@ -565,8 +565,8 @@ function add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' )
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param string $option Name of option to remove. Expected to not be SQL-escaped. * @param string $option Name of the option to delete. Expected to not be SQL-escaped.
* @return bool True, if option is successfully deleted. False on failure. * @return bool True if the option was deleted, false otherwise.
*/ */
function delete_option( $option ) { function delete_option( $option ) {
global $wpdb; global $wpdb;
@ -641,7 +641,7 @@ function delete_option( $option ) {
* @since 2.8.0 * @since 2.8.0
* *
* @param string $transient Transient name. Expected to not be SQL-escaped. * @param string $transient Transient name. Expected to not be SQL-escaped.
* @return bool true if successful, false otherwise * @return bool True if the transient was deleted, false otherwise.
*/ */
function delete_transient( $transient ) { function delete_transient( $transient ) {
@ -768,7 +768,7 @@ function get_transient( $transient ) {
* @param mixed $value Transient value. Must be serializable if non-scalar. * @param mixed $value Transient value. Must be serializable if non-scalar.
* Expected to not be SQL-escaped. * Expected to not be SQL-escaped.
* @param int $expiration Optional. Time until expiration in seconds. Default 0 (no expiration). * @param int $expiration Optional. Time until expiration in seconds. Default 0 (no expiration).
* @return bool False if value was not set and true if value was set. * @return bool True if the value was set, false otherwise.
*/ */
function set_transient( $transient, $value, $expiration = 0 ) { function set_transient( $transient, $value, $expiration = 0 ) {
@ -990,7 +990,7 @@ function wp_user_settings() {
* *
* @param string $name The name of the setting. * @param string $name The name of the setting.
* @param string $default Optional default value to return when $name is not set. * @param string $default Optional default value to return when $name is not set.
* @return mixed the last saved user setting or the default value/false if it doesn't exist. * @return mixed The last saved user setting or the default value/false if it doesn't exist.
*/ */
function get_user_setting( $name, $default = false ) { function get_user_setting( $name, $default = false ) {
$all_user_settings = get_all_user_settings(); $all_user_settings = get_all_user_settings();
@ -1009,7 +1009,8 @@ function get_user_setting( $name, $default = false ) {
* *
* @param string $name The name of the setting. * @param string $name The name of the setting.
* @param string $value The value for the setting. * @param string $value The value for the setting.
* @return bool|null True if set successfully, false if not. Null if the current user can't be established. * @return bool|null True if set successfully, false otherwise.
* Null if the current user is not a member of the site.
*/ */
function set_user_setting( $name, $value ) { function set_user_setting( $name, $value ) {
if ( headers_sent() ) { if ( headers_sent() ) {
@ -1032,7 +1033,8 @@ function set_user_setting( $name, $value ) {
* @since 2.7.0 * @since 2.7.0
* *
* @param string $names The name or array of names of the setting to be deleted. * @param string $names The name or array of names of the setting to be deleted.
* @return bool|null True if deleted successfully, false if not. Null if the current user can't be established. * @return bool|null True if deleted successfully, false otherwise.
* Null if the current user is not a member of the site.
*/ */
function delete_user_setting( $names ) { function delete_user_setting( $names ) {
if ( headers_sent() ) { if ( headers_sent() ) {
@ -1064,7 +1066,7 @@ function delete_user_setting( $names ) {
* *
* @global array $_updated_user_settings * @global array $_updated_user_settings
* *
* @return array the last saved user settings or empty array. * @return array The last saved user settings or empty array.
*/ */
function get_all_user_settings() { function get_all_user_settings() {
global $_updated_user_settings; global $_updated_user_settings;
@ -1107,8 +1109,8 @@ function get_all_user_settings() {
* @global array $_updated_user_settings * @global array $_updated_user_settings
* *
* @param array $user_settings User settings. * @param array $user_settings User settings.
* @return bool|null False if the current user can't be found, null if the current * @return bool|null True if set successfully, false if the current user could not be found.
* user is not a super admin or a member of the site, otherwise true. * Null if the current user is not a member of the site.
*/ */
function wp_set_all_user_settings( $user_settings ) { function wp_set_all_user_settings( $user_settings ) {
global $_updated_user_settings; global $_updated_user_settings;
@ -1165,8 +1167,8 @@ function delete_all_user_settings() {
* *
* @see get_network_option() * @see get_network_option()
* *
* @param string $option Name of option to retrieve. Expected to not be SQL-escaped. * @param string $option Name of the option to retrieve. Expected to not be SQL-escaped.
* @param mixed $default Optional value to return if option doesn't exist. Default false. * @param mixed $default Optional. Value to return if the option doesn't exist. Default false.
* @param bool $deprecated Whether to use cache. Multisite only. Always set to true. * @param bool $deprecated Whether to use cache. Multisite only. Always set to true.
* @return mixed Value set for the option. * @return mixed Value set for the option.
*/ */
@ -1184,9 +1186,9 @@ function get_site_option( $option, $default = false, $deprecated = true ) {
* *
* @see add_network_option() * @see add_network_option()
* *
* @param string $option Name of option to add. Expected to not be SQL-escaped. * @param string $option Name of the option to add. Expected to not be SQL-escaped.
* @param mixed $value Option value, can be anything. Expected to not be SQL-escaped. * @param mixed $value Option value, can be anything. Expected to not be SQL-escaped.
* @return bool False if the option was not added. True if the option was added. * @return bool True if the option was added, false otherwise.
*/ */
function add_site_option( $option, $value ) { function add_site_option( $option, $value ) {
return add_network_option( null, $option, $value ); return add_network_option( null, $option, $value );
@ -1200,8 +1202,8 @@ function add_site_option( $option, $value ) {
* *
* @see delete_network_option() * @see delete_network_option()
* *
* @param string $option Name of option to remove. Expected to not be SQL-escaped. * @param string $option Name of the option to delete. Expected to not be SQL-escaped.
* @return bool True, if succeed. False, if failure. * @return bool True if the option was deleted, false otherwise.
*/ */
function delete_site_option( $option ) { function delete_site_option( $option ) {
return delete_network_option( null, $option ); return delete_network_option( null, $option );
@ -1215,9 +1217,9 @@ function delete_site_option( $option ) {
* *
* @see update_network_option() * @see update_network_option()
* *
* @param string $option Name of option. Expected to not be SQL-escaped. * @param string $option Name of the option. Expected to not be SQL-escaped.
* @param mixed $value Option value. Expected to not be SQL-escaped. * @param mixed $value Option value. Expected to not be SQL-escaped.
* @return bool False if value was not updated. True if value was updated. * @return bool True if the value was updated, false otherwise.
*/ */
function update_site_option( $option, $value ) { function update_site_option( $option, $value ) {
return update_network_option( null, $option, $value ); return update_network_option( null, $option, $value );
@ -1233,7 +1235,7 @@ function update_site_option( $option, $value ) {
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param int $network_id ID of the network. Can be null to default to the current network ID. * @param int $network_id ID of the network. Can be null to default to the current network ID.
* @param string $option Name of option to retrieve. Expected to not be SQL-escaped. * @param string $option Name of the option to retrieve. Expected to not be SQL-escaped.
* @param mixed $default Optional. Value to return if the option doesn't exist. Default false. * @param mixed $default Optional. Value to return if the option doesn't exist. Default false.
* @return mixed Value set for the option. * @return mixed Value set for the option.
*/ */
@ -1367,9 +1369,9 @@ function get_network_option( $network_id, $option, $default = false ) {
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param int $network_id ID of the network. Can be null to default to the current network ID. * @param int $network_id ID of the network. Can be null to default to the current network ID.
* @param string $option Name of option to add. Expected to not be SQL-escaped. * @param string $option Name of the option to add. Expected to not be SQL-escaped.
* @param mixed $value Option value, can be anything. Expected to not be SQL-escaped. * @param mixed $value Option value, can be anything. Expected to not be SQL-escaped.
* @return bool False if option was not added and true if option was added. * @return bool True if the option was added, false otherwise.
*/ */
function add_network_option( $network_id, $option, $value ) { function add_network_option( $network_id, $option, $value ) {
global $wpdb; global $wpdb;
@ -1492,8 +1494,8 @@ function add_network_option( $network_id, $option, $value ) {
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param int $network_id ID of the network. Can be null to default to the current network ID. * @param int $network_id ID of the network. Can be null to default to the current network ID.
* @param string $option Name of option to remove. Expected to not be SQL-escaped. * @param string $option Name of the option to delete. Expected to not be SQL-escaped.
* @return bool True, if succeed. False, if failure. * @return bool True if the option was deleted, false otherwise.
*/ */
function delete_network_option( $network_id, $option ) { function delete_network_option( $network_id, $option ) {
global $wpdb; global $wpdb;
@ -1585,9 +1587,9 @@ function delete_network_option( $network_id, $option ) {
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param int $network_id ID of the network. Can be null to default to the current network ID. * @param int $network_id ID of the network. Can be null to default to the current network ID.
* @param string $option Name of option. Expected to not be SQL-escaped. * @param string $option Name of the option. Expected to not be SQL-escaped.
* @param mixed $value Option value. Expected to not be SQL-escaped. * @param mixed $value Option value. Expected to not be SQL-escaped.
* @return bool False if value was not updated and true if value was updated. * @return bool True if the value was updated, false otherwise.
*/ */
function update_network_option( $network_id, $option, $value ) { function update_network_option( $network_id, $option, $value ) {
global $wpdb; global $wpdb;
@ -1713,7 +1715,7 @@ function update_network_option( $network_id, $option, $value ) {
* @since 2.9.0 * @since 2.9.0
* *
* @param string $transient Transient name. Expected to not be SQL-escaped. * @param string $transient Transient name. Expected to not be SQL-escaped.
* @return bool True if successful, false otherwise * @return bool True if the transient was deleted, false otherwise.
*/ */
function delete_site_transient( $transient ) { function delete_site_transient( $transient ) {
@ -1841,7 +1843,7 @@ function get_site_transient( $transient ) {
* 167 characters or fewer in length. * 167 characters or fewer in length.
* @param mixed $value Transient value. Expected to not be SQL-escaped. * @param mixed $value Transient value. Expected to not be SQL-escaped.
* @param int $expiration Optional. Time until expiration in seconds. Default 0 (no expiration). * @param int $expiration Optional. Time until expiration in seconds. Default 0 (no expiration).
* @return bool False if value was not set and true if value was set. * @return bool True if the value was set, false otherwise.
*/ */
function set_site_transient( $transient, $value, $expiration = 0 ) { function set_site_transient( $transient, $value, $expiration = 0 ) {