Docs: Improve documentation for various option functions.
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
parent
0df921c96d
commit
fcafa02a04
@ -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 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.
|
||||
* @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 ) {
|
||||
$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 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 ) {
|
||||
$id = (int) $id;
|
||||
@ -454,7 +454,7 @@ function delete_blog_option( $id, $option ) {
|
||||
* @param string $option The option key.
|
||||
* @param mixed $value The option value.
|
||||
* @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 ) {
|
||||
$id = (int) $id;
|
||||
|
||||
@ -23,7 +23,7 @@
|
||||
*
|
||||
* @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.
|
||||
* @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.
|
||||
*
|
||||
* @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 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.
|
||||
* Accepts 'yes'|true to enable or 'no'|false to disable. For non-existent options,
|
||||
* 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 ) {
|
||||
global $wpdb;
|
||||
@ -457,13 +457,13 @@ function update_option( $option, $value, $autoload = null ) {
|
||||
*
|
||||
* @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.
|
||||
* Expected to not be SQL-escaped.
|
||||
* @param string $deprecated Optional. Description. Not used anymore.
|
||||
* @param string|bool $autoload Optional. Whether to load the option when WordPress starts up.
|
||||
* 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' ) {
|
||||
global $wpdb;
|
||||
@ -565,8 +565,8 @@ function add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' )
|
||||
*
|
||||
* @global wpdb $wpdb WordPress database abstraction object.
|
||||
*
|
||||
* @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.
|
||||
* @param string $option Name of the option to delete. Expected to not be SQL-escaped.
|
||||
* @return bool True if the option was deleted, false otherwise.
|
||||
*/
|
||||
function delete_option( $option ) {
|
||||
global $wpdb;
|
||||
@ -641,7 +641,7 @@ function delete_option( $option ) {
|
||||
* @since 2.8.0
|
||||
*
|
||||
* @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 ) {
|
||||
|
||||
@ -768,7 +768,7 @@ function get_transient( $transient ) {
|
||||
* @param mixed $value Transient value. Must be serializable if non-scalar.
|
||||
* Expected to not be SQL-escaped.
|
||||
* @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 ) {
|
||||
|
||||
@ -990,7 +990,7 @@ function wp_user_settings() {
|
||||
*
|
||||
* @param string $name The name of the setting.
|
||||
* @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 ) {
|
||||
$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 $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 ) {
|
||||
if ( headers_sent() ) {
|
||||
@ -1032,7 +1033,8 @@ function set_user_setting( $name, $value ) {
|
||||
* @since 2.7.0
|
||||
*
|
||||
* @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 ) {
|
||||
if ( headers_sent() ) {
|
||||
@ -1064,7 +1066,7 @@ function delete_user_setting( $names ) {
|
||||
*
|
||||
* @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() {
|
||||
global $_updated_user_settings;
|
||||
@ -1107,8 +1109,8 @@ function get_all_user_settings() {
|
||||
* @global array $_updated_user_settings
|
||||
*
|
||||
* @param array $user_settings User settings.
|
||||
* @return bool|null False if the current user can't be found, null if the current
|
||||
* user is not a super admin or a member of the site, otherwise true.
|
||||
* @return bool|null True if set successfully, false if the current user could not be found.
|
||||
* Null if the current user is not a member of the site.
|
||||
*/
|
||||
function wp_set_all_user_settings( $user_settings ) {
|
||||
global $_updated_user_settings;
|
||||
@ -1165,8 +1167,8 @@ function delete_all_user_settings() {
|
||||
*
|
||||
* @see get_network_option()
|
||||
*
|
||||
* @param string $option Name of option to retrieve. Expected to not be SQL-escaped.
|
||||
* @param mixed $default Optional value to return if option doesn't exist. Default false.
|
||||
* @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 bool $deprecated Whether to use cache. Multisite only. Always set to true.
|
||||
* @return mixed Value set for the option.
|
||||
*/
|
||||
@ -1184,9 +1186,9 @@ function get_site_option( $option, $default = false, $deprecated = true ) {
|
||||
*
|
||||
* @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.
|
||||
* @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 ) {
|
||||
return add_network_option( null, $option, $value );
|
||||
@ -1200,8 +1202,8 @@ function add_site_option( $option, $value ) {
|
||||
*
|
||||
* @see delete_network_option()
|
||||
*
|
||||
* @param string $option Name of option to remove. Expected to not be SQL-escaped.
|
||||
* @return bool True, if succeed. False, if failure.
|
||||
* @param string $option Name of the option to delete. Expected to not be SQL-escaped.
|
||||
* @return bool True if the option was deleted, false otherwise.
|
||||
*/
|
||||
function delete_site_option( $option ) {
|
||||
return delete_network_option( null, $option );
|
||||
@ -1215,9 +1217,9 @@ function delete_site_option( $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.
|
||||
* @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 ) {
|
||||
return update_network_option( null, $option, $value );
|
||||
@ -1233,7 +1235,7 @@ function update_site_option( $option, $value ) {
|
||||
* @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 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.
|
||||
* @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.
|
||||
*
|
||||
* @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.
|
||||
* @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 ) {
|
||||
global $wpdb;
|
||||
@ -1492,8 +1494,8 @@ function add_network_option( $network_id, $option, $value ) {
|
||||
* @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 string $option Name of option to remove. Expected to not be SQL-escaped.
|
||||
* @return bool True, if succeed. False, if failure.
|
||||
* @param string $option Name of the option to delete. Expected to not be SQL-escaped.
|
||||
* @return bool True if the option was deleted, false otherwise.
|
||||
*/
|
||||
function delete_network_option( $network_id, $option ) {
|
||||
global $wpdb;
|
||||
@ -1585,9 +1587,9 @@ function delete_network_option( $network_id, $option ) {
|
||||
* @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 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.
|
||||
* @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 ) {
|
||||
global $wpdb;
|
||||
@ -1713,7 +1715,7 @@ function update_network_option( $network_id, $option, $value ) {
|
||||
* @since 2.9.0
|
||||
*
|
||||
* @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 ) {
|
||||
|
||||
@ -1841,7 +1843,7 @@ function get_site_transient( $transient ) {
|
||||
* 167 characters or fewer in length.
|
||||
* @param mixed $value Transient value. Expected to not be SQL-escaped.
|
||||
* @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 ) {
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user