Implement support for watching for changes in settings

This implements a dream of one day being able to listen for changes in a settings to react to them, regardless of which device actually changed the setting. The use case for this kind of thing is extremely limited, but when it is needed it should be more than powerful enough.

docs/settings.md

@@ -131,6 +131,32 @@ SettingsStore.getValue(...); // this will return the value set in `setValue` abo
 ```
 
 
+## Watching for changes
+
+Most use cases do not need to set up a watcher because they are able to react to changes as they are made, or the changes which are made are not significant enough for it to matter. Watchers are intended to be used in scenarios where it is important to react to changes made by other logged in devices. Typically, this would be done within the component itself, however the component should not be aware of the intricacies of setting inversion or remapping to particular data structures. Instead, a generic watcher interface is provided on `SettingsStore` to watch (and subsequently unwatch) for changes in a setting.
+
+An example of a watcher in action would be:
+
+```javascript
+class MyComponent extends React.Component {
+    
+    settingWatcherRef = null;
+    
+    componentWillMount() {
+        this.settingWatcherRef = SettingsStore.watchSetting("roomColor", "!example:matrix.org", (settingName, roomId, level, newVal) => {
+            // Always re-read the setting value from the store to avoid reacting to changes which do not have a consequence. For example, the
+            // room color could have been changed at the device level, but an account override prevents that change from making a difference.
+           const actualVal = SettingsStore.getValue(settingName, "!example:matrix.org");
+           if (actualVal !== this.state.color) this.setState({color: actualVal});
+        });
+    }
+    
+    componentWillUnmount() {
+        SettingsStore.unwatchSetting(this.settingWatcherRef);
+    }
+}
+```
+
 
 # Maintainers Reference
 
@@ -159,3 +185,10 @@ Features automatically get considered as `disabled` if they are not listed in th
 ```
 
 If `enableLabs` is true in the configuration, the default for features becomes `"labs"`.
+
+### Watchers
+
+Watchers can appear complicated under the hood: the request to watch a setting is actually forked off to individual handlers for watching. This means that the handlers need to track their changes and listen for remote changes where possible, but also makes it much easier for the `SettingsStore` to react to changes. The handler is going to know the best things to listen for (specific events, account data, etc) and thus it is left as a responsibility for the handler to track changes. 
+
+In practice, handlers which rely on remote changes (account data, room events, etc) will always attach a listener to the `MatrixClient`. They then watch for changes to events they care about and send off appropriate updates to the generalized `WatchManager` - a class specifically designed to deduplicate the logic of managing watchers. The handlers which are localized to the local client (device) generally just trigger the `WatchManager` when they manipulate the setting themselves as there's nothing to really 'watch'.
+