DOCS: Remove docs around platformUserAccount (#1400).

Rene Damm · web-flow · commit 428fb82921a9 · 2021-09-03T12:43:03.000+02:00
diff --git a/Packages/com.unity.inputsystem/CHANGELOG.md b/Packages/com.unity.inputsystem/CHANGELOG.md
@@ -14,6 +14,7 @@ however, it has to be formatted properly to pass verification tests.
 
 - Fixed `InvalidCastException: Specified cast is not valid.` and `InvalidOperationException: Already have an event buffer set! Was OnUpdate() called recursively?` when upgrading from 1.1.0-pre.5 or earlier. If you experience this issue you can also restart the editor to resolve it.
 - Fixed `InputDeviceChange.Destroyed` not being available, now it's correctly marked as obsolete instead.
+- Removed documentation around platform user account management of `InputUser` which was ahead of actual backend support for the feature.
 
 ## [1.1.0] - 2021-08-27
 
diff --git a/Packages/com.unity.inputsystem/Documentation~/UserManagement.md b/Packages/com.unity.inputsystem/Documentation~/UserManagement.md
@@ -4,7 +4,7 @@ The Input System supports multi-user management through the [`InputUser`](../api
 
 >__Note__: The user management API is quite low-level in nature. The stock functionality of [`PlayerInputManager`](Components.md#playerinputmanager-component) (see [Components](./Components.md)) provides an easier way to set up user management. The API described here is useful when you want more control over user management.
 
-In the Input System, each [`InputUser`](../api/UnityEngine.InputSystem.Users.InputUser.html) represents a human interacting with the application. For example, you can have multiple users playing a game together on a single computer or device (local multiplayer), where each user has one or more [paired Input Devices](#device-pairing). A user might be associated with a platform [user account](#user-account-management), if the platform and Devices support it.
+In the Input System, each [`InputUser`](../api/UnityEngine.InputSystem.Users.InputUser.html) represents a human interacting with the application. For example, you can have multiple users playing a game together on a single computer or device (local multiplayer), where each user has one or more [paired Input Devices](#device-pairing).
 
 The [`PlayerInputManager`](Components.md#playerinputmanager-component) class uses [`InputUser`](../api/UnityEngine.InputSystem.Users.InputUser.html) internally to handle users.
 
@@ -34,16 +34,6 @@ If paired Input Devices disconnect during the session, the system notifies the [
 
 To get notifications about these changes, subscribe to the [`InputUser.onChange`](../api/UnityEngine.InputSystem.Users.InputUser.html#UnityEngine_InputSystem_Users_InputUser_onChange) event.
 
-## User account management
-
-The Input System can associate a user with a platform-specific user account, if both the platform and the Devices support this. Consoles commonly support this functionality. Platforms that support user account association are Xbox One, PlayStation 4, Nintendo Switch, and UWP.
-
-Use the [`platformUserAccountHandle`](../api/UnityEngine.InputSystem.Users.InputUser.html#UnityEngine_InputSystem_Users_InputUser_platformUserAccountHandle) property to query the associated user account for an [`InputUser`](../api/UnityEngine.InputSystem.Users.InputUser.html). This property gets determined when the user is first [paired to a Device](#device-pairing), and the Device has any platform user information the Input System can query.
-
-The account associated with an InputUser might change if the player uses the platform's facilities to switch to a different account ([`InputUser.onChange`](../api/UnityEngine.InputSystem.Users.InputUser.html#UnityEngine_InputSystem_Users_InputUser_onChange) receives an `InputUserChange.AccountChanged` notification).
-
-Note that for WSA/UWP apps, the *User Account Information* capability must be enabled for the app in order for user information to come through on input devices.
-
 ## Debugging
 
 Check the debugger documentation to learn [how to debug active users](Debugging.md#debugging-users-and-playerinput).
diff --git a/Packages/com.unity.inputsystem/InputSystem/Plugins/Users/InputUser.cs b/Packages/com.unity.inputsystem/InputSystem/Plugins/Users/InputUser.cs
@@ -29,19 +29,6 @@ namespace UnityEngine.InputSystem.Users
     /// This can be useful in setups such as split-keyboard (e.g. one user using left side of keyboard and the
     /// other the right one) use or hotseat-style gameplay (e.g. two players taking turns on the same game controller).
     ///
-    /// A user may be associated with a platform user account (<see cref="platformUserAccountHandle"/>), if supported by the
-    /// platform and the devices used. Support for this is commonly found on consoles. Note that the account
-    /// associated with an InputUser may change if the player uses the system's facilities to switch to a different
-    /// account (<see cref="InputUserChange.AccountChanged"/>). On Xbox and Switch, this may also be initiated from
-    /// the application by passing <see cref="InputUserPairingOptions.ForcePlatformUserAccountSelection"/> to
-    /// <see cref="PerformPairingWithDevice"/>.
-    ///
-    /// Platforms that support user account association are <see cref="RuntimePlatform.XboxOne"/>,
-    /// <see cref="RuntimePlatform.PS4"/>, <see cref="RuntimePlatform.Switch"/>, <see cref="RuntimePlatform.WSAPlayerX86"/>,
-    /// <see cref="RuntimePlatform.WSAPlayerX64"/>, and <see cref="RuntimePlatform.WSAPlayerARM"/>. Note that
-    /// for WSA/UWP apps, the "User Account Information" capability must be enabled for the app in order for
-    /// user information to come through on input devices.
-    ///
     /// Note that the InputUser API, like <see cref="InputAction"/>) is a play mode-only feature. When exiting play mode,
     /// all users are automatically removed and all devices automatically unpaired.
     /// </remarks>
@@ -107,62 +94,13 @@ public int index
         /// The ID of a user is internally assigned and cannot be changed over its lifetime. No two users, even
         /// if not concurrently active, will receive the same ID.
         ///
-        /// Note that this is not the same as the platform's internal user ID (if relevant on the current
-        /// platform). To get the ID that the platform uses to identify the user, use <see cref="platformUserAccountHandle"/>.
-        ///
         /// The ID stays valid and unique even if the user is removed and no longer <see cref="valid"/>.
         /// </remarks>
-        /// <seealso cref="platformUserAccountHandle"/>
         public uint id => m_Id;
 
-        /// <summary>
-        /// If the user is is associated with a user account at the platform level, this is the handle used by the
-        /// underlying platform API for the account.
-        /// </summary>
-        /// <remarks>
-        /// Users may be associated with user accounts defined by the platform we are running on. Consoles, for example,
-        /// have user account management built into the OS and marketplaces like Steam also have APIs for user management.
-        ///
-        /// If this property is not <c>null</c>, it is the handle associated with the user at the platform level. This can
-        /// be used, for example, to call platform-specific APIs to fetch additional information about the user (such as
-        /// user profile images).
-        ///
-        /// Be aware that there may be multiple InputUsers that have the same platformUserAccountHandle in case the platform
-        /// allows different players to log in on the same user account.
-        /// </remarks>
-        /// <seealso cref="platformUserAccountName"/>
-        /// <seealso cref="platformUserAccountId"/>
-        /// <seealso cref="InputUserChange.AccountChanged"/>
+        ////TODO: bring documentation for these back when user management is implemented on Xbox and PS
         public InputUserAccountHandle? platformUserAccountHandle => s_GlobalState.allUserData[index].platformUserAccountHandle;
-
-        /// <summary>
-        /// Human-readable name assigned to the user account at the platform level.
-        /// </summary>
-        /// <remarks>
-        /// This property will be <c>null</c> on platforms that do not have user account management. In that case,
-        /// <see cref="platformUserAccountHandle"/> will be <c>null</c> as well.
-        ///
-        /// On platforms such as Xbox, PS4, and Switch, the user name will be the name of the user as logged in on the platform.
-        /// </remarks>
-        /// <seealso cref="platformUserAccountHandle"/>
-        /// <seealso cref="platformUserAccountId"/>
-        /// <seealso cref="InputUserChange.AccountChanged"/>
-        /// <seealso cref="InputUserChange.AccountNameChanged"/>
         public string platformUserAccountName => s_GlobalState.allUserData[index].platformUserAccountName;
-
-        /// <summary>
-        /// Platform-specific user ID that is valid across sessions even if the <see cref="platformUserAccountName"/> of
-        /// the user changes.
-        /// </summary>
-        /// <remarks>
-        /// This is only valid if <see cref="platformUserAccountHandle"/> is not null.
-        ///
-        /// Use this to, for example, associate application settings with the user. For display in UIs, use
-        /// <see cref="platformUserAccountName"/> instead.
-        /// </remarks>
-        /// <seealso cref="platformUserAccountHandle"/>
-        /// <seealso cref="platformUserAccountName"/>
-        /// <seealso cref="InputUserChange.AccountChanged"/>
         public string platformUserAccountId => s_GlobalState.allUserData[index].platformUserAccountId;
 
         ////REVIEW: Does it make sense to track used devices separately from paired devices?
@@ -853,64 +791,6 @@ public static InputUser CreateUserWithoutPairedDevices()
         /// user has a control scheme that is currently activated (<see cref="controlScheme"/>), then <see cref="controlSchemeMatch"/>
         /// will also automatically update to reflect the matching of devices to the control scheme's device requirements.
         ///
-        /// If the given device is associated with a user account at the platform level (queried through
-        /// <see cref="QueryPairedUserAccountCommand"/>), the user's platform account details (<see cref="platformUserAccountHandle"/>,
-        /// <see cref="platformUserAccountName"/>, and <see cref="platformUserAccountId"/>) are updated accordingly. In this case,
-        /// <see cref="InputUserChange.AccountChanged"/> or <see cref="InputUserChange.AccountNameChanged"/> may be signalled.
-        /// through <see cref="onChange"/>.
-        ///
-        /// If the given device is not associated with a user account at the platform level, but it does
-        /// respond to <see cref="InitiateUserAccountPairingCommand"/>, then the device is NOT immediately paired
-        /// to the user. Instead, pairing is deferred to until after an account selection has been made by the user.
-        /// In this case, <see cref="InputUserChange.AccountSelectionInProgress"/> will be signalled through <see cref="onChange"/>
-        /// and <see cref="InputUserChange.AccountChanged"/> will be signalled once the user has selected an account or
-        /// <see cref="InputUserChange.AccountSelectionCanceled"/> will be signalled if the user cancels account
-        /// selection. The device will be paired to the user once account selection is complete.
-        ///
-        /// This behavior is most useful on Xbox and Switch to require the user to choose which account to play with. Note that
-        /// if the device is already associated with a user account, account selection will not be initiated. However,
-        /// it can be explicitly forced to be performed by using <see
-        /// cref="InputUserPairingOptions.ForcePlatformUserAccountSelection"/>. This is useful,
-        /// for example, to allow the user to explicitly switch accounts.
-        ///
-        /// On Xbox and Switch, to permit playing even on devices that do not currently have an associated user account,
-        /// use <see cref="InputUserPairingOptions.ForceNoPlatformUserAccountSelection"/>.
-        ///
-        /// On PS4, devices will always have associated user accounts meaning that the returned InputUser will always
-        /// have updated platform account details.
-        ///
-        /// Note that user account queries and initiating account selection can be intercepted by the application. For
-        /// example, on Switch where user account pairing is not stored at the platform level, one can, for example, both
-        /// implement custom pairing logic as well as a custom account selection UI by intercepting <see cref="QueryPairedUserAccountCommand"/>
-        /// and <seealso cref="InitiateUserAccountPairingCommand"/>.
-        ///
-        /// <example>
-        /// <code>
-        /// InputSystem.onDeviceCommand +=
-        ///     (device, commandPtr, runtime) =>
-        ///     {
-        ///         // Dealing with InputDeviceCommands requires handling raw pointers.
-        ///         unsafe
-        ///         {
-        ///             // We're only looking for QueryPairedUserAccountCommand and InitiateUserAccountPairingCommand here.
-        ///             if (commandPtr->type != QueryPairedUserAccountCommand.Type &amp;&amp; commandPtr->type != InitiateUserAccountPairingCommand)
-        ///                 return null; // Command not handled.
-        ///
-        ///             // Check if device is the one your interested in. As an example, we look for Switch gamepads
-        ///             // here.
-        ///             if (!(device is Npad))
-        ///                 return null; // Command not handled.
-        ///
-        ///             // If it's a QueryPairedUserAccountCommand, see if we have a user ID to use with the Npad
-        ///             // based on last time the application ran.
-        ///             if (commandPtr->type == QueryPairedUserAccountCommand.Type)
-        ///             {
-        ///                 ////TODO
-        ///         }
-        ///     };
-        /// </code>
-        /// </example>
-        /// </remarks>
         /// <example>
         /// <code>
         /// // Pair device to new user.
@@ -920,6 +800,7 @@ public static InputUser CreateUserWithoutPairedDevices()
         /// InputUser.PerformPairingWithDevice(wand2, user: user);
         /// </code>
         /// </example>
+        /// </remarks>
         /// <seealso cref="pairedDevices"/>
         /// <seealso cref="UnpairDevice"/>
         /// <seealso cref="UnpairDevices"/>
@@ -1481,21 +1362,7 @@ private static long UpdatePlatformUserAccount(int userIndex, InputDevice device)
             return queryResult;
         }
 
-        /// <summary>
-        /// If the given device is paired to a user account at the platform level, return the platform user
-        /// account details.
-        /// </summary>
-        /// <param name="device">Any input device.</param>
-        /// <param name="platformAccountHandle">Receives the platform user account handle or null.</param>
-        /// <param name="platformAccountName">Receives the platform user account name or null.</param>
-        /// <param name="platformAccountId">Receives the platform user account ID or null.</param>
-        /// <returns>True if the device is paired to a user account, false otherwise.</returns>
-        /// <remarks>
-        /// Sends <see cref="QueryPairedUserAccountCommand"/> to the device.
-        /// </remarks>
-        /// <seealso cref="QueryPairedUserAccountCommand.handle"/>
-        /// <seealso cref="QueryPairedUserAccountCommand.name"/>
-        /// <seealso cref="QueryPairedUserAccountCommand.id"/>
+        ////TODO: bring documentation for these back when user management is implemented on Xbox and PS
         private static long QueryPairedPlatformUserAccount(InputDevice device,
             out InputUserAccountHandle? platformAccountHandle, out string platformAccountName, out string platformAccountId)
         {
diff --git a/Packages/com.unity.inputsystem/InputSystem/Plugins/Users/InputUserChange.cs b/Packages/com.unity.inputsystem/InputSystem/Plugins/Users/InputUserChange.cs
@@ -73,51 +73,11 @@ public enum InputUserChange
         /// <seealso cref="InputUser.lostDevices"/>
         DeviceRegained,
 
-        /// <summary>
-        /// A user has either switched accounts at the platform level.
-        /// </summary>
-        /// <remarks>
-        /// This means that the user is now playing with a different user account. This is relevant for persisting
-        /// settings as well as for features such as achievements.
-        ///
-        /// This is detected via <see cref="DeviceConfigurationEvent"/>s. If a device is currently paired to a user
-        /// but then notifies that its configuration has changed and the platform user we have on record for the
-        /// device is no longer the same, this notification is sent after the platform user data (<see cref="InputUser.platformUserAccountHandle"/>
-        /// and related APIs) has been updated.
-        ///
-        /// In response, the application may want to update the user name displayed in the UI. When displaying user
-        /// profile images, an updated image should also be requested from the platform APIs using the user account
-        /// information obtained from <see cref="InputUser"/>.
-        ///
-        /// Note that the notification may also mean that the device is no longer associated with a user account.
-        /// In that case <see cref="InputUser.platformUserAccountHandle"/> will be invalid.
-        /// </remarks>
-        /// <seealso cref="InputUser.platformUserAccountHandle"/>
-        /// <seealso cref="InputUser.platformUserAccountName"/>
-        /// <seealso cref="InputUser.platformUserAccountId"/>
+        ////TODO: bring documentation for these back when user management is implemented on Xbox and PS
         AccountChanged,
-
         AccountNameChanged,
-
-        /// <summary>
-        /// The user was asked to select an account during the device pairing process.
-        /// </summary>
-        /// <remarks>
-        /// In most cases, it makes sense to pause the game while account picking is in progress.
-        /// </remarks>
         AccountSelectionInProgress,
-
-        /// <summary>
-        /// The user canceled the account selection process that was initiated.
-        /// </summary>
         AccountSelectionCanceled,
-
-        /// <summary>
-        /// The user completed the account selection process.
-        /// </summary>
-        /// <remarks>
-        /// Like <see cref="AccountChanged"/>, this means that the account details may have changed.
-        /// </remarks>
         AccountSelectionComplete,
 
         ////REVIEW: send notifications about the matching status of the control scheme? maybe ControlSchemeActivated, ControlSchemeDeactivated,
