Added documentation for authentication builders

Author: ivaylokenov

src/MyTested.Mvc/Builders/Authentication/BaseUserBuilder.cs

@@ -5,12 +5,34 @@
     using System.Security.Claims;
     using Utilities.Extensions;
 
+    /// <summary>
+    /// Base class for creating mocked authenticated <see cref="ClaimsIdentity"/>.
+    /// </summary>
     public abstract class BaseUserBuilder
     {
+        /// <summary>
+        /// Default identifier (Id) of the built <see cref="ClaimsIdentity"/> - "TestId".
+        /// </summary>
         protected const string DefaultIdentifier = "TestId";
+
+        /// <summary>
+        /// Default username of the built <see cref="ClaimsIdentity"/> - "TestUser".
+        /// </summary>
         protected const string DefaultUsername = "TestUser";
+
+        /// <summary>
+        /// Default authentication type of the built <see cref="ClaimsIdentity"/> - "Passport".
+        /// </summary>
         protected const string DefaultAuthenticationType = "Passport";
+
+        /// <summary>
+        /// Default type of the name claim - <see cref="ClaimTypes.Name"/>.
+        /// </summary>
         protected const string DefaultNameType = ClaimTypes.Name;
+
+        /// <summary>
+        /// Default type of the role claim - <see cref="ClaimTypes.Role"/>.
+        /// </summary>
         protected const string DefaultRoleType = ClaimTypes.Role;
 
         private readonly ICollection<Claim> claims;
@@ -19,6 +41,9 @@ public abstract class BaseUserBuilder
         private string nameType;
         private string roleType;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BaseUserBuilder" /> class.
+        /// </summary>
         protected BaseUserBuilder()
         {
             this.authenticationType = DefaultAuthenticationType;
@@ -27,7 +52,15 @@ protected BaseUserBuilder()
 
             this.claims = new List<Claim>();
         }
-        
+
+        /// <summary>
+        /// Creates new authenticated claims identity by using the provided claims and authentication type.
+        /// </summary>
+        /// <param name="claims">Collection of claims to add to the authenticated identity.</param>
+        /// <param name="authenticationType">Authentication type to use for the authenticated identity.</param>
+        /// <param name="nameType">Type of the username claim. Default is <see cref="ClaimTypes.Name"/>.</param>
+        /// <param name="roleType">Type of the role claim. Default is <see cref="ClaimTypes.Role"/>.</param>
+        /// <returns>Mocked <see cref="ClaimsIdentity"/>.</returns>
         protected static ClaimsIdentity CreateAuthenticatedClaimsIdentity(
             ICollection<Claim> claims = null,
             string authenticationType = null,
@@ -52,6 +85,10 @@ protected static ClaimsIdentity CreateAuthenticatedClaimsIdentity(
             return new ClaimsIdentity(claims, authenticationType, nameType, roleType);
         }
 
+        /// <summary>
+        /// Creates new authenticated claims identity by using the accumulated claims and authentication type.
+        /// </summary>
+        /// <returns>Mocked <see cref="ClaimsIdentity"/>.</returns>
         protected ClaimsIdentity GetAuthenticatedClaimsIdentity()
         {
             return CreateAuthenticatedClaimsIdentity(
@@ -61,51 +98,92 @@ protected ClaimsIdentity GetAuthenticatedClaimsIdentity()
                 this.roleType);
         }
 
+        /// <summary>
+        /// Sets type of the username claim. Default is <see cref="ClaimTypes.Name"/>.
+        /// </summary>
+        /// <param name="nameType">Type to set on the username claim.</param>
         protected void AddNameType(string nameType)
         {
             this.nameType = nameType;
         }
 
+        /// <summary>
+        /// Sets type of the role claim. Default is <see cref="ClaimTypes.Role"/>.
+        /// </summary>
+        /// <param name="roleType">Type to set on the role claim.</param>
         protected void AddRoleType(string roleType)
         {
             this.roleType = roleType;
         }
 
+        /// <summary>
+        /// Sets identifier claim to the built <see cref="ClaimsIdentity"/>.
+        /// </summary>
+        /// <param name="identifier">Value of the identifier claim - <see cref="ClaimTypes.NameIdentifier"/>.</param>
         protected void AddIdentifier(string identifier)
         {
             this.AddClaim(ClaimTypes.NameIdentifier, identifier);
         }
 
+        /// <summary>
+        /// Sets username claims to the built <see cref="ClaimsIdentity"/>.
+        /// </summary>
+        /// <param name="username">Value of the username claim. Default claim type is <see cref="ClaimTypes.Name"/>.</param>
         protected void AddUsername(string username)
         {
             this.AddClaim(this.nameType, username);
         }
 
+        /// <summary>
+        /// Adds claim to the built <see cref="ClaimsIdentity"/>.
+        /// </summary>
+        /// <param name="claim">The <see cref="Claim"/> to add.</param>
         protected void AddClaim(Claim claim)
         {
             this.claims.Add(claim);
         }
 
+        /// <summary>
+        /// Adds claims to the built <see cref="ClaimsIdentity"/>.
+        /// </summary>
+        /// <param name="claims">Enumerable of <see cref="Claim"/> to add.</param>
         protected void AddClaims(IEnumerable<Claim> claims)
         {
             claims.ForEach(c => this.AddClaim(c));
         }
 
+        /// <summary>
+        /// Adds authentication type to the built <see cref="ClaimsIdentity"/>.
+        /// </summary>
+        /// <param name="authenticationType">Authentication type to add. Default is "Passport".</param>
         protected void AddAuthenticationType(string authenticationType)
         {
             this.authenticationType = authenticationType;
         }
 
+        /// <summary>
+        /// Adds role to the built <see cref="ClaimsIdentity"/>.
+        /// </summary>
+        /// <param name="role">Value of the role claim. Default claim type is <see cref="ClaimTypes.Role"/>.</param>
         protected void AddRole(string role)
         {
             this.AddClaim(this.roleType, role);
         }
 
+        /// <summary>
+        /// Adds roles to the built <see cref="ClaimsIdentity"/>.
+        /// </summary>
+        /// <param name="roles">Enumerable of roles to add.</param>
         protected void AddRoles(IEnumerable<string> roles)
         {
             roles.ForEach(r => this.AddRole(r));
         }
 
+        /// <summary>
+        /// Adds claim to the built <see cref="ClaimsIdentity"/>.
+        /// </summary>
+        /// <param name="type">Type of the claim to add.</param>
+        /// <param name="value">Value of the claim to add.</param>
         private void AddClaim(string type, string value)
         {
             this.claims.Add(new Claim(type, value));

src/MyTested.Mvc/Builders/Authentication/ClaimsIdentityBuilder.cs

@@ -5,122 +5,93 @@
     using System.Security.Claims;
     using Contracts.Authentication;
 
+    /// <summary>
+    /// Used for creating mocked authenticated <see cref="ClaimsIdentity"/>.
+    /// </summary>
     public class ClaimsIdentityBuilder : BaseUserBuilder, IAndClaimsIdentityBuilder
     {
+        /// <inheritdoc />
         public IAndClaimsIdentityBuilder WithNameType(string nameType)
         {
             this.AddNameType(nameType);
             return this;
         }
 
+        /// <inheritdoc />
         public IAndClaimsIdentityBuilder WithRoleType(string roleType)
         {
             this.AddRoleType(roleType);
             return this;
         }
 
-        /// <summary>
-        /// Used for setting ID to the claims identity. If such is not provided, "TestId" is used by default.
-        /// </summary>
-        /// <param name="identifier">The user Id to set.</param>
-        /// <returns>The same claims identity builder.</returns>
+        /// <inheritdoc />
         public IAndClaimsIdentityBuilder WithIdentifier(string identifier)
         {
             this.AddIdentifier(identifier);
             return this;
         }
 
-        /// <summary>
-        /// Used for setting username to the claims identity. If such is not provided, "TestUser" is used by default.
-        /// </summary>
-        /// <param name="username">The username to set.</param>
-        /// <returns>The same claims identity builder.</returns>
+        /// <inheritdoc />
         public IAndClaimsIdentityBuilder WithUsername(string username)
         {
             this.AddUsername(username);
             return this;
         }
-        
+
+        /// <inheritdoc />
         public IAndClaimsIdentityBuilder WithClaim(string type, string value)
         {
             return this.WithClaim(new Claim(type, value));
         }
 
-        /// <summary>
-        /// Used for adding claim to the claims identity.
-        /// </summary>
-        /// <param name="claim">The claim to add.</param>
-        /// <returns>The same claims identity builder.</returns>
+        /// <inheritdoc />
         public IAndClaimsIdentityBuilder WithClaim(Claim claim)
         {
             this.AddClaim(claim);
             return this;
         }
 
-        /// <summary>
-        /// Used for adding claims to the claims identity.
-        /// </summary>
-        /// <param name="claims">The claims to add.</param>
-        /// <returns>The same claims identity builder.</returns>
+        /// <inheritdoc />
         public IAndClaimsIdentityBuilder WithClaims(IEnumerable<Claim> claims)
         {
             this.AddClaims(claims);
             return this;
         }
 
-        /// <summary>
-        /// Used for adding claims to the claims identity.
-        /// </summary>
-        /// <param name="claims">The claims to add.</param>
-        /// <returns>The same claims identity builder.</returns>
+        /// <inheritdoc />
         public IAndClaimsIdentityBuilder WithClaims(params Claim[] claims)
         {
             return this.WithClaims(claims.AsEnumerable());
         }
 
-        /// <summary>
-        /// Used for setting authentication type to the claims identity. If such is not provided, "Passport" is used by default.
-        /// </summary>
-        /// <param name="authenticationType">The authentication type to set.</param>
-        /// <returns>The same claims identity builder.</returns>
+        /// <inheritdoc />
         public IAndClaimsIdentityBuilder WithAuthenticationType(string authenticationType)
         {
             this.AddAuthenticationType(authenticationType);
             return this;
         }
 
-        /// <summary>
-        /// Used for adding role to claims identity.
-        /// </summary>
-        /// <param name="role">The role to add.</param>
-        /// <returns>The same claims identity builder.</returns>
+        /// <inheritdoc />
         public IAndClaimsIdentityBuilder InRole(string role)
         {
             this.AddRole(role);
             return this;
         }
 
-        /// <summary>
-        /// Used for adding multiple roles to claims identity.
-        /// </summary>
-        /// <param name="roles">Collection of roles to add.</param>
-        /// <returns>The same claims identity builder.</returns>
+        /// <inheritdoc />
         public IAndClaimsIdentityBuilder InRoles(IEnumerable<string> roles)
         {
             this.AddRoles(roles);
             return this;
         }
 
-        /// <summary>
-        /// Used for adding multiple roles to claims identity.
-        /// </summary>
-        /// <param name="roles">Roles to add.</param>
-        /// <returns>The same claims identity builder.</returns>
+        /// <inheritdoc />
         public IAndClaimsIdentityBuilder InRoles(params string[] roles)
         {
             return this.InRoles(roles.AsEnumerable());
         }
 
+        /// <inheritdoc />
         public IClaimsIdentityBuilder AndAlso()
         {
             return this;