Improved wording in documentation

Author: sharwell

src/corelib/Core/Providers/IIdentityProvider.cs

@@ -50,7 +50,7 @@ public interface IIdentityProvider
         /// <summary>
         /// Lists global roles for a specified user. Excludes tenant roles.
         /// </summary>
-        /// <param name="userId">The user's ID. The behavior is unspecified if this value is not obtained from <see cref="User.Id"/>.</param>
+        /// <param name="userId">The user's ID. This is obtained from <see cref="User.Id">User.Id</see>.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the <see cref="DefaultIdentity"/> for the current provider instance will be used.</param>
         /// <returns>A collection of <see cref="Role"/> objects describing the roles for the specified user.</returns>
         /// <exception cref="ArgumentNullException">If <paramref name="userId"/> is <c>null</c>.</exception>
@@ -163,7 +163,7 @@ public interface IIdentityProvider
         /// <summary>
         /// Deletes the specified user from the account.
         /// </summary>
-        /// <param name="userId">The user ID. The behavior is unspecified if this is not obtained from <see cref="User.Id"/> or <see cref="NewUser.Id"/>.</param>
+        /// <param name="userId">The user ID. This is obtained from <see cref="User.Id"/> or <see cref="NewUser.Id"/>.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the <see cref="DefaultIdentity"/> for the current provider instance will be used.</param>
         /// <returns><c>true</c> if the user was successfully deleted; otherwise, <c>false</c>.</returns>
         /// <exception cref="ArgumentNullException">If <paramref name="userId"/> is <c>null</c>.</exception>
@@ -181,7 +181,7 @@ public interface IIdentityProvider
         /// <summary>
         /// Lists the credentials for the specified user.
         /// </summary>
-        /// <param name="userId">The user ID. The behavior is unspecified if this is not obtained from <see cref="User.Id"/> or <see cref="NewUser.Id"/>.</param>
+        /// <param name="userId">The user ID. This is obtained from <see cref="User.Id"/> or <see cref="NewUser.Id"/>.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the <see cref="DefaultIdentity"/> for the current provider instance will be used.</param>
         /// <returns>List of <see cref="UserCredential"/> objects describing the credentials of the specified user.</returns>
         /// <exception cref="ArgumentNullException">If <paramref name="userId"/> is <c>null</c>.</exception>
@@ -228,7 +228,7 @@ public interface IIdentityProvider
         /// <summary>
         /// Gets the specified user credential.
         /// </summary>
-        /// <param name="userId">The user ID. The behavior is unspecified if this is not obtained from <see cref="User.Id"/> or <see cref="NewUser.Id"/>.</param>
+        /// <param name="userId">The user ID. This is obtained from <see cref="User.Id"/> or <see cref="NewUser.Id"/>.</param>
         /// <param name="credentialKey">The credential key.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the <see cref="DefaultIdentity"/> for the current provider instance will be used.</param>
         /// <returns>The <see cref="UserCredential"/> details for the specified credentials type.</returns>

src/corelib/Core/Providers/INetworksProvider.cs

@@ -68,7 +68,7 @@ public interface INetworksProvider
         /// <summary>
         /// Retrieve details for the specified network.
         /// </summary>
-        /// <param name="networkId">ID of the network to retrieve. The behavior is unspecified if this is not obtained from <see cref="CloudNetwork.Id"/>.</param>
+        /// <param name="networkId">ID of the network to retrieve. This is obtained from <see cref="CloudNetwork.Id"/>.</param>
         /// <param name="region">The region in which to execute this action. If not specified, the user's default region will be used.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the default identity for the current provider instance will be used.</param>
         /// <returns>A <see cref="CloudNetwork"/> instance containing the network details.</returns>
@@ -91,7 +91,7 @@ public interface INetworksProvider
         /// <summary>
         /// Deletes the specified network. <remarks>You cannot delete an isolated network unless the network is not attached to any server.</remarks>
         /// </summary>
-        /// <param name="networkId">ID of the network to delete. The behavior is unspecified if this is not obtained from <see cref="CloudNetwork.Id"/>.</param>
+        /// <param name="networkId">ID of the network to delete. This is obtained from <see cref="CloudNetwork.Id"/>.</param>
         /// <param name="region">The region in which to execute this action. If not specified, the user's default region will be used.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the default identity for the current provider instance will be used.</param>
         /// <returns><c>true</c> if the network was successfully deleted; otherwise, <c>false</c>.</returns>

src/corelib/Providers/Rackspace/IExtendedCloudIdentityProvider.cs

@@ -33,7 +33,7 @@ public interface IExtendedCloudIdentityProvider : IIdentityProvider
         /// <summary>
         /// Lists all users for a given role.
         /// </summary>
-        /// <param name="roleId">The role ID. The behavior is unspecified if this is not obtained from <see cref="Role.Id"/>.</param>
+        /// <param name="roleId">The role ID. This is obtained from <see cref="Role.Id">Role.Id</see>.</param>
         /// <param name="enabled">Allows you to filter enabled or un-enabled users. If the value is <c>null</c>, a provider-specific default value is used.</param>
         /// <param name="marker">The index of the last item in the previous list. Used for pagination. If the value is <c>null</c>, the list starts at the beginning.</param>
         /// <param name="limit">Indicates the maximum number of items to return. Used for pagination. If the value is <c>null</c>, a provider-specific default value is used.</param>
@@ -67,7 +67,7 @@ public interface IExtendedCloudIdentityProvider : IIdentityProvider
         /// <summary>
         /// Gets details about the specified role.
         /// </summary>
-        /// <param name="roleId">The role ID. The behavior is unspecified if this is not obtained from <see cref="Role.Id">Role.Id</see>.</param>
+        /// <param name="roleId">The role ID. This is obtained from <see cref="Role.Id">Role.Id</see>.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the default identity for the current provider instance will be used.</param>
         /// <returns>A <see cref="Role"/> containing the details of the role.</returns>
         /// <exception cref="ArgumentNullException">If <paramref name="roleId"/> is <c>null</c>.</exception>
@@ -85,8 +85,8 @@ public interface IExtendedCloudIdentityProvider : IIdentityProvider
         /// <summary>
         /// Adds the specified global role to the user.
         /// </summary>
-        /// <param name="userId">The user ID. The behavior is unspecified if this is not obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
-        /// <param name="roleId">The role ID. The behavior is unspecified if this is not obtained from <see cref="Role.Id"/>.</param>
+        /// <param name="userId">The user ID. This is obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
+        /// <param name="roleId">The role ID. This is obtained from <see cref="Role.Id"/>.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the default identity for the current provider instance will be used.</param>
         /// <returns><c>true</c> if the role was removed from the user; otherwise, <c>false</c>.</returns>
         /// <exception cref="ArgumentNullException">
@@ -112,8 +112,8 @@ public interface IExtendedCloudIdentityProvider : IIdentityProvider
         /// <summary>
         /// Deletes the specified global role from the user.
         /// </summary>
-        /// <param name="userId">The user ID. The behavior is unspecified if this is not obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
-        /// <param name="roleId">The role ID. The behavior is unspecified if this is not obtained from <see cref="Role.Id"/>.</param>
+        /// <param name="userId">The user ID. This is obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
+        /// <param name="roleId">The role ID. This is obtained from <see cref="Role.Id"/>.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the default identity for the current provider instance will be used.</param>
         /// <returns><c>true</c> if the role was removed from the user; otherwise, <c>false</c>.</returns>
         /// <exception cref="ArgumentNullException">
@@ -145,7 +145,7 @@ public interface IExtendedCloudIdentityProvider : IIdentityProvider
         /// method, where the credentials are always specified in the form of an API key.
         /// </remarks>
         /// <returns>A <see cref="UserCredential"/> object containing the updated user information.</returns>
-        /// <param name="userId">The user ID. The behavior is unspecified if this is not obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
+        /// <param name="userId">The user ID. This is obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
         /// <param name="apiKey">The new API key.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the default identity for the current provider instance will be used.</param>
         /// <exception cref="ArgumentNullException">
@@ -176,7 +176,7 @@ public interface IExtendedCloudIdentityProvider : IIdentityProvider
         /// <see href="http://docs.openstack.org/api/openstack-identity-service/2.0/content/DELETE_deleteUserCredential_v2.0_users__userId__OS-KSADM_credentials__credential-type__.html">Delete User Credentials</see>
         /// method, where the credentials are always specified in the form of an API key.
         /// </remarks>
-        /// <param name="userId">The user ID. The behavior is unspecified if this is not obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
+        /// <param name="userId">The user ID. This is obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the default identity for the current provider instance will be used.</param>
         /// <returns><c>true</c> if the credentials were removed from the user; otherwise, <c>false</c>.</returns>
         /// <exception cref="ArgumentNullException">If <paramref name="userId"/> is <c>null</c>.</exception>
@@ -194,7 +194,7 @@ public interface IExtendedCloudIdentityProvider : IIdentityProvider
         /// <summary>
         /// Sets the password for the specified user.
         /// </summary>
-        /// <param name="userId">The user ID. The behavior is unspecified if this is not obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
+        /// <param name="userId">The user ID. This is obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
         /// <param name="password">The new password.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the default identity for the current provider instance will be used.</param>
         /// <returns><c>true</c> if the operation succeeded; otherwise, <c>false</c>.</returns>
@@ -250,7 +250,7 @@ public interface IExtendedCloudIdentityProvider : IIdentityProvider
         /// <summary>
         /// Updates the username and password for the specified user.
         /// </summary>
-        /// <param name="userId">The user ID. The behavior is unspecified if this is not obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
+        /// <param name="userId">The user ID. This is obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
         /// <param name="username">The new username.</param>
         /// <param name="password">The new password.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the default identity for the current provider instance will be used.</param>
@@ -321,7 +321,7 @@ public interface IExtendedCloudIdentityProvider : IIdentityProvider
         /// <see href="http://docs.openstack.org/api/openstack-identity-service/2.0/content/POST_updateUserCredential_v2.0_users__userId__OS-KSADM_credentials__credential-type__.html">Update User Credentials</see>
         /// method, where the credentials are always specified in the form of an API key.
         /// </remarks>
-        /// <param name="userId">The user ID. The behavior is unspecified if this is not obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
+        /// <param name="userId">The user ID. This is obtained from <see cref="NewUser.Id"/> or <see cref="User.Id"/>.</param>
         /// <param name="username">The new username.</param>
         /// <param name="apiKey">The new API key.</param>
         /// <param name="identity">The cloud identity to use for this request. If not specified, the default identity for the current provider instance will be used.</param>