initial data types: Give UserSettings a jsdoc and align definition

To prepare this type to be reused for a new PATCH /settings binding,
coming next.

This makes one functional change to the types: since
`available_notification_sounds` and `emojiset_choices` no longer
appear in `UserSettings`, the `UserSettingsUpdateEvent` type gets
narrower by excluding those too. That's correct; we don't expect an
event that updates those two rogue "user settings".

Author: chrisbobbe

src/api/initialDataTypes.js

@@ -598,6 +598,13 @@ export type InitialDataUpdateMessageFlags = $ReadOnly<{|
   |}>,
 |}>;
 
+/**
+ * The user settings, stored on the server.
+ *
+ * See:
+ * - PATCH /settings doc: https://zulip.com/api/update-settings
+ * - POST /register doc: https://zulip.com/api/register-queue
+ */
 // Assumes FL 89+, because servers added user_settings to the /register
 // response in FL 89.
 //
@@ -654,8 +661,6 @@ export type UserSettings = {|
   +desktop_icon_count_display: 1 | 2 | 3,
   +realm_name_in_notifications: boolean,
   +presence_enabled: boolean,
-  +available_notification_sounds: $ReadOnlyArray<string>,
-  +emojiset_choices: $ReadOnlyArray<{| +key: string, +text: string |}>,
 
   // TODO(server-5.0): New in FL 105.
   +send_private_typing_notifications?: boolean,
@@ -680,7 +685,15 @@ export type UserSettings = {|
 // TODO(server-5.0): Remove FL 89+ comment.
 export type InitialDataUserSettings = {|
   // TODO(server-5.0): New in FL 89, for requesting clients, so assumes 89.
-  +user_settings?: UserSettings,
+  +user_settings?: {|
+    ...UserSettings,
+
+    // These appear here even though they aren't really user settings at
+    // all. We're hoping to drop them from here because of that:
+    //   https://chat.zulip.org/#narrow/stream/378-api-design/topic/User.20settings.20discrepancies/near/1456533
+    +available_notification_sounds: $ReadOnlyArray<string>,
+    +emojiset_choices: $ReadOnlyArray<{| +key: string, +text: string |}>,
+  |},
 |};
 
 /**

src/realm/__tests__/realmReducer-test.js

@@ -310,7 +310,6 @@ describe('realmReducer', () => {
             initialState[statePropertyName] = initialStateValue;
 
             const expectedState = { ...initialState };
-            // $FlowFixMe[prop-missing]
             /* $FlowFixMe[incompatible-type]: Trust that the caller passed the
                right kind of value for its chosen key. */
             expectedState[statePropertyName] = eventValue;

src/settings/__tests__/settingsReducer-test.js

@@ -7,7 +7,7 @@ import {
   EVENT_UPDATE_GLOBAL_NOTIFICATIONS_SETTINGS,
   EVENT,
 } from '../../actionConstants';
-import type { UserSettings } from '../../api/initialDataTypes';
+import type { InitialData, UserSettings } from '../../api/initialDataTypes';
 import { EventTypes } from '../../api/eventTypes';
 import settingsReducer from '../settingsReducer';
 import * as eg from '../../__tests__/lib/exampleData';
@@ -54,7 +54,9 @@ describe('settingsReducer', () => {
             user_settings: {
               /* $FlowIgnore[incompatible-cast] - testing modern servers, which
                  send user_settings. */
-              ...(eg.action.register_complete.data.user_settings: UserSettings),
+              ...(eg.action.register_complete.data.user_settings: $NonMaybeType<
+                InitialData['user_settings'],
+              >),
               enable_offline_push_notifications: true,
               enable_online_push_notifications: true,
               enable_stream_push_notifications: true,