Address code review changes and add XML comments

Octokit/Models/AuthorizationUpdate.cs

@@ -1,22 +1,34 @@
-using System.Diagnostics.CodeAnalysis;
+using System.Collections.Generic;
 
 namespace Octokit
 {
+    /// <summary>
+    /// Used to create a new authorization.
+    /// </summary>
     public class AuthorizationUpdate
     {
         /// <summary>
-        /// Replace scopes with this list.
+        /// Replaces the authorization scopes with this list.
         /// </summary>
-        [SuppressMessage("Microsoft.Performance", "CA1819:PropertiesShouldNotReturnArrays", Justification = "Special type of model object that only updates none-null fields.")]
-        public string[] Scopes { get; set; }
+        public IEnumerable<string> Scopes { get; set; }
 
         /// <summary>
-        /// Notes about this particular <see cref="Authorization"/>.
+        /// A list of scopes to add to this authorization.
+        /// </summary>
+        public IEnumerable<string> AddScopes { get; set; }
+
+        /// <summary>
+        /// A list of scopes to remove from this authorization.
+        /// </summary>
+        public IEnumerable<string> RemoveScopes { get; set; }
+
+        /// <summary>
+        /// An optional note to remind you what the OAuth token is for.
         /// </summary>
         public string Note { get; set; }
 
         /// <summary>
-        /// A url for more information about notes.
+        // An optional URL to remind you what app the OAuth token is for.
         /// </summary>
         public string NoteUrl { get; set; }
     }