user preferences: Add some information about types to the phpdoc

User options saved to the database and retrieved get converted
to strings, but defaults and set but not yet saved vaues don't.
This behavior can be confusing.

When a value equal to the default is set for a given user, that
value won't be written to the database; defaults are represented
by the lack of a database row. This behavior can also be
confusing.

Update the phpdoc of some user preferences related methods and
variables to make these things clearer.

Change-Id: I32a18b30f007c97015e6d641379ce60ab6ac7ed7

2 files changed, 21 insertions, 2 deletions

diff --git a/includes/user/Options/UserOptionsLookup.php b/includes/user/Options/UserOptionsLookup.php
index 24f43b40d7c5..065944b14a9d 100644
--- a/includes/user/Options/UserOptionsLookup.php
+++ b/includes/user/Options/UserOptionsLookup.php
@@ -68,7 +68,9 @@ abstract class UserOptionsLookup implements IDBAccessObject {
 	 * @param mixed|null $defaultOverride A default value returned if the option does not exist
 	 * @param bool $ignoreHidden Whether to ignore the effects of $wgHiddenPrefs
 	 * @param int $queryFlags A bit field composed of READ_XXX flags
-	 * @return mixed|null User's current value for the option
+	 * @return mixed|null User's current value for the option,
+	 *   Note that while option values retrieved from the database are always strings, default
+	 *   values and values set within the current request and not yet saved may be of another type.
 	 * @see getBoolOption()
 	 * @see getIntOption()
 	 */
diff --git a/includes/user/Options/UserOptionsManager.php b/includes/user/Options/UserOptionsManager.php
index 0c899224ce25..d7d1d4059aa7 100644
--- a/includes/user/Options/UserOptionsManager.php
+++ b/includes/user/Options/UserOptionsManager.php
@@ -205,9 +205,26 @@ class UserOptionsManager extends UserOptionsLookup {
 	 *
 	 * You need to call saveOptions() to actually write to the database.
 	 *
+	 * $val should be null or a string. Other types are accepted for B/C with legacy
+	 * code but can result in surprising behavior and are discouraged. Values are always
+	 * stored as strings in the database, so if you pass a non-string value, it will be
+	 * eventually converted; but before the call to saveOptions(), getOption() will return
+	 * the passed value from instance cache without any type conversion.
+	 *
+	 * A null value means resetting the option to its default value (removing the user_properties
+	 * row). Passing in the same value as the default value fo the user has the same result.
+	 * This behavior supports some level of type juggling - e.g. if the default value is 1,
+	 * and you pass in '1', the option will be reset to its default value.
+	 *
+	 * When an option is reset to its default value, that means whenever the default value
+	 * is changed in the site configuration, the user preference for this user will also change.
+	 * There is no way to set a user preference to be the same as the default but avoid it
+	 * changing when the default changes. You can instead use $wgConditionalUserOptions to
+	 * split the default based on user registration date.
+	 *
 	 * @param UserIdentity $user
 	 * @param string $oname The option to set
-	 * @param mixed $val New value to set
+	 * @param mixed $val New value to set.
 	 */
 	public function setOption( UserIdentity $user, string $oname, $val ) {
 		// Explicitly NULL values should refer to defaults