Doc comment update

src/Microsoft.AspNetCore.Authorization/IAuthorizationService.cs

@@ -16,24 +16,39 @@ namespace Microsoft.AspNetCore.Authorization
         /// Checks if a user meets a specific set of requirements for the specified resource
         /// </summary>
         /// <param name="user">The user to evaluate the requirements against.</param>
-        /// <param name="resource">The resource to evaluate the requirements against.</param>
+        /// <param name="resource">
+        /// An optional resource the policy should be checked with.
+        /// If a resource is not required for policy evaluation you may pass null as the value.
+        /// </param>
         /// <param name="requirements">The requirements to evaluate.</param>
         /// <returns>
-        /// A flag indicating whether authorization has succeded.
-        /// This value is <value>true</value> when the user fulfills the policy otherwise <value>false</value>.
+        /// A flag indicating whether authorization has succeeded.
+        /// This value is <value>true</value> when the user fulfills the policy; otherwise <value>false</value>.
         /// </returns>
+        /// <remarks>
+        /// Resource is an optional parameter and may be null. Please ensure that you check it is not 
+        /// null before acting upon it.
+        /// </remarks>
         Task<bool> AuthorizeAsync(ClaimsPrincipal user, object resource, IEnumerable<IAuthorizationRequirement> requirements);
 
         /// <summary>
         /// Checks if a user meets a specific authorization policy
         /// </summary>
         /// <param name="user">The user to check the policy against.</param>
-        /// <param name="resource">The resource the policy should be checked with.</param>
+        /// <param name="resource">
+        /// An optional resource the policy should be checked with.
+        /// If a resource is not required for policy evaluation you may pass null as the value.
+        /// </param>
         /// <param name="policyName">The name of the policy to check against a specific context.</param>
         /// <returns>
-        /// A flag indicating whether authorization has succeded.
-        /// This value is <value>true</value> when the user fulfills the policy otherwise <value>false</value>.
+        /// A flag indicating whether authorization has succeeded.
+        /// Returns a flag indicating whether the user, and optional resource has fulfilled the policy.    
+        /// <value>true</value> when the the policy has been fulfilled; otherwise <value>false</value>.
         /// </returns>
+        /// <remarks>
+        /// Resource is an optional parameter and may be null. Please ensure that you check it is not 
+        /// null before acting upon it.
+        /// </remarks>
         Task<bool> AuthorizeAsync(ClaimsPrincipal user, object resource, string policyName);
     }
 }