diff -r 34716fd837a4 -r be944660c56a wp/wp-includes/option.php
--- a/wp/wp-includes/option.php	Tue Dec 15 15:52:01 2020 +0100
+++ b/wp/wp-includes/option.php	Wed Sep 21 18:19:35 2022 +0200
@@ -9,15 +9,58 @@
 /**
  * Retrieves an option value based on an option name.
  *
- * If the option does not exist or does not have a value, then the return value
- * will be false. This is useful to check whether you need to install an option
- * and is commonly used during installation of plugin options and to test
- * whether upgrading is required.
+ * If the option does not exist, and a default value is not provided,
+ * boolean false is returned. This could be used to check whether you need
+ * to initialize an option during installation of a plugin, however that
+ * can be done better by using add_option() which will not overwrite
+ * existing options.
+ *
+ * Not initializing an option and using boolean `false` as a return value
+ * is a bad practice as it triggers an additional database query.
+ *
+ * The type of the returned value can be different from the type that was passed
+ * when saving or updating the option. If the option value was serialized,
+ * then it will be unserialized when it is returned. In this case the type will
+ * be the same. For example, storing a non-scalar value like an array will
+ * return the same array.
+ *
+ * In most cases non-string scalar and null values will be converted and returned
+ * as string equivalents.
  *
- * If the option was serialized then it will be unserialized when it is returned.
+ * Exceptions:
+ * 1. When the option has not been saved in the database, the `$default` value
+ *    is returned if provided. If not, boolean `false` is returned.
+ * 2. When one of the Options API filters is used: {@see 'pre_option_{$option}'},
+ *    {@see 'default_option_{$option}'}, or {@see 'option_{$option}'}, the returned
+ *    value may not match the expected type.
+ * 3. When the option has just been saved in the database, and get_option()
+ *    is used right after, non-string scalar and null values are not converted to
+ *    string equivalents and the original type is returned.
+ *
+ * Examples:
+ *
+ * When adding options like this: `add_option( 'my_option_name', 'value' );`
+ * and then retrieving them with `get_option( 'my_option_name' );`, the returned
+ * values will be:
  *
- * Any scalar values will be returned as strings. You may coerce the return type of
- * a given option by registering an {@see 'option_$option'} filter callback.
+ * `false` returns `string(0) ""`
+ * `true`  returns `string(1) "1"`
+ * `0`     returns `string(1) "0"`
+ * `1`     returns `string(1) "1"`
+ * `'0'`   returns `string(1) "0"`
+ * `'1'`   returns `string(1) "1"`
+ * `null`  returns `string(0) ""`
+ *
+ * When adding options with non-scalar values like
+ * `add_option( 'my_array', array( false, 'str', null ) );`, the returned value
+ * will be identical to the original as it is serialized before saving
+ * it in the database:
+ *
+ *    array(3) {
+ *        [0] => bool(false)
+ *        [1] => string(3) "str"
+ *        [2] => NULL
+ *    }
  *
  * @since 1.5.0
  *
@@ -25,7 +68,11 @@
  *
  * @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.
+ * @return mixed Value of the option. A value of any type may be returned, including
+ *               scalar (string, boolean, float, integer), null, array, object.
+ *               Scalar and null values will be returned as strings as long as they originate
+ *               from a database stored option value. If there is no option in the database,
+ *               boolean `false` is returned.
  */
 function get_option( $option, $default = false ) {
 	global $wpdb;
@@ -1057,8 +1104,8 @@
  *
  * @since 2.7.0
  *
- * @param string $name    The name of the setting.
- * @param string $default Optional default value to return when $name is not set.
+ * @param string       $name    The name of the setting.
+ * @param string|false $default Optional. Default value to return when $name is not set. Default false.
  * @return mixed The last saved user setting or the default value/false if it doesn't exist.
  */
 function get_user_setting( $name, $default = false ) {
@@ -2322,9 +2369,9 @@
  * @global array $new_allowed_options
  * @global array $wp_registered_settings
  *
- * @param string   $option_group The settings group name used during registration.
- * @param string   $option_name  The name of the option to unregister.
- * @param callable $deprecated   Deprecated.
+ * @param string          $option_group The settings group name used during registration.
+ * @param string          $option_name  The name of the option to unregister.
+ * @param callable|string $deprecated   Deprecated.
  */
 function unregister_setting( $option_group, $option_name, $deprecated = '' ) {
 	global $new_allowed_options, $wp_registered_settings;