add documentation

src/Privileged/AuthorizationActions.cs

@@ -1,6 +1,12 @@
 namespace Privileged;
 
+/// <summary>
+/// Authorization action defaults
+/// </summary>
 public static class AuthorizationActions
 {
+    /// <summary>
+    /// Special keyword represents any action will be matched
+    /// </summary>
     public const string All = "all";
 }

src/Privileged/AuthorizationBuilder.cs

@@ -1,9 +1,22 @@
 namespace Privileged;
 
+/// <summary>
+/// An <see cref="AuthorizationContext"/> builder
+/// </summary>
 public class AuthorizationBuilder
 {
     private readonly List<AuthorizationRule> _rules = [];
 
+    /// <summary>
+    /// Create a rule allowing the specified <paramref name="action"/>, <paramref name="subject"/> and optional <paramref name="fields"/>.
+    /// </summary>
+    /// <param name="action">The action to allow.</param>
+    /// <param name="subject">The subject to allow.</param>
+    /// <param name="fields">The optional fields to allow.</param>
+    /// <returns>The builder for chaining method calls</returns>
+    /// <exception cref="ArgumentException">
+    /// Action or Subject cannot be null or whitespace.
+    /// </exception>
     public AuthorizationBuilder Allow(string action, string subject, IEnumerable<string>? fields = null)
     {
         if (string.IsNullOrWhiteSpace(action))
@@ -18,6 +31,16 @@ public AuthorizationBuilder Allow(string action, string subject, IEnumerable<str
         return this;
     }
 
+    /// <summary>
+    /// Create a rule forbidding the specified <paramref name="action"/>, <paramref name="subject"/> and optional <paramref name="fields"/>.
+    /// </summary>
+    /// <param name="action">The action to forbid.</param>
+    /// <param name="subject">The subject to forbid.</param>
+    /// <param name="fields">The optional fields to forbid.</param>
+    /// <returns>The builder for chaining method calls</returns>
+    /// <exception cref="ArgumentException">
+    /// Action or Subject cannot be null or whitespace.
+    /// </exception>
     public AuthorizationBuilder Forbid(string action, string subject, IEnumerable<string>? fields = null)
     {
         if (string.IsNullOrWhiteSpace(action))
@@ -32,6 +55,12 @@ public AuthorizationBuilder Forbid(string action, string subject, IEnumerable<st
         return this;
     }
 
+    /// <summary>
+    /// Creates the <see cref="AuthorizationContext"/> from the rules specified in <see cref="Allow"/> or <see cref="Forbid"/> methods.
+    /// </summary>
+    /// <returns>An instance of <see cref="AuthorizationContext"/> with the specified rules</returns>
+    /// <seealso cref="Allow"/>
+    /// <seealso cref="Forbid"/>
     public AuthorizationContext Build()
     {
         return new AuthorizationContext(_rules);

src/Privileged/AuthorizationBuilderExtensions.cs

@@ -1,7 +1,20 @@
 namespace Privileged;
 
+/// <summary>
+/// An <see cref="AuthorizationContext"/> builder extension methods
+/// </summary>
 public static class AuthorizationBuilderExtensions
 {
+    /// <summary>
+    /// Create a rule allowing the specified <paramref name="actions" />, <paramref name="subjects" /> and optional <paramref name="fields" />.
+    /// </summary>
+    /// <param name="builder">The <see cref="AuthorizationContext"/> builder.</param>
+    /// <param name="actions">The actions to allow.</param>
+    /// <param name="subjects">The subjects to allow.</param>
+    /// <param name="fields">The optional fields to allow.</param>
+    /// <returns>
+    /// The builder for chaining method calls
+    /// </returns>
     public static AuthorizationBuilder Allow(this AuthorizationBuilder builder, IEnumerable<string> actions, IEnumerable<string> subjects, IEnumerable<string>? fields = null)
     {
         if (builder == null)
@@ -27,6 +40,16 @@ public static AuthorizationBuilder Allow(this AuthorizationBuilder builder, IEnu
         return builder;
     }
 
+    /// <summary>
+    /// Create a rule allowing the specified <paramref name="actions" />, <paramref name="subject" /> and optional <paramref name="fields" />.
+    /// </summary>
+    /// <param name="builder">The <see cref="AuthorizationContext"/> builder.</param>
+    /// <param name="actions">The actions to allow.</param>
+    /// <param name="subject">The subject to allow.</param>
+    /// <param name="fields">The optional fields to allow.</param>
+    /// <returns>
+    /// The builder for chaining method calls
+    /// </returns>
     public static AuthorizationBuilder Allow(this AuthorizationBuilder builder, IEnumerable<string> actions, string subject, IEnumerable<string>? fields = null)
     {
         if (builder == null)
@@ -47,6 +70,16 @@ public static AuthorizationBuilder Allow(this AuthorizationBuilder builder, IEnu
         return builder;
     }
 
+    /// <summary>
+    /// Create a rule allowing the specified <paramref name="action" />, <paramref name="subjects" /> and optional <paramref name="fields" />.
+    /// </summary>
+    /// <param name="builder">The <see cref="AuthorizationContext"/> builder.</param>
+    /// <param name="action">The action to allow.</param>
+    /// <param name="subjects">The subjects to allow.</param>
+    /// <param name="fields">The optional fields to allow.</param>
+    /// <returns>
+    /// The builder for chaining method calls
+    /// </returns>
     public static AuthorizationBuilder Allow(this AuthorizationBuilder builder, string action, IEnumerable<string> subjects, IEnumerable<string>? fields = null)
     {
         if (builder == null)
@@ -67,6 +100,16 @@ public static AuthorizationBuilder Allow(this AuthorizationBuilder builder, stri
         return builder;
     }
 
+    /// <summary>
+    /// Create a rule forbidding the specified <paramref name="actions" />, <paramref name="subjects" /> and optional <paramref name="fields" />.
+    /// </summary>
+    /// <param name="builder">The <see cref="AuthorizationContext"/> builder.</param>
+    /// <param name="actions">The actions to forbid.</param>
+    /// <param name="subjects">The subjects to forbid.</param>
+    /// <param name="fields">The optional fields to forbid.</param>
+    /// <returns>
+    /// The builder for chaining method calls
+    /// </returns>
     public static AuthorizationBuilder Forbid(this AuthorizationBuilder builder, IEnumerable<string> actions, IEnumerable<string> subjects, IEnumerable<string>? fields = null)
     {
         if (builder == null)
@@ -92,6 +135,16 @@ public static AuthorizationBuilder Forbid(this AuthorizationBuilder builder, IEn
         return builder;
     }
 
+    /// <summary>
+    /// Create a rule forbidding the specified <paramref name="actions" />, <paramref name="subject" /> and optional <paramref name="fields" />.
+    /// </summary>
+    /// <param name="builder">The <see cref="AuthorizationContext"/> builder.</param>
+    /// <param name="actions">The actions to forbid.</param>
+    /// <param name="subject">The subject to forbid.</param>
+    /// <param name="fields">The optional fields to forbid.</param>
+    /// <returns>
+    /// The builder for chaining method calls
+    /// </returns>
     public static AuthorizationBuilder Forbid(this AuthorizationBuilder builder, IEnumerable<string> actions, string subject, IEnumerable<string>? fields = null)
     {
         if (builder == null)
@@ -112,6 +165,16 @@ public static AuthorizationBuilder Forbid(this AuthorizationBuilder builder, IEn
         return builder;
     }
 
+    /// <summary>
+    /// Create a rule forbidding the specified <paramref name="action" />, <paramref name="subjects" /> and optional <paramref name="fields" />.
+    /// </summary>
+    /// <param name="builder">The <see cref="AuthorizationContext"/> builder.</param>
+    /// <param name="action">The action to forbid.</param>
+    /// <param name="subjects">The subjects to forbid.</param>
+    /// <param name="fields">The optional fields to forbid.</param>
+    /// <returns>
+    /// The builder for chaining method calls
+    /// </returns>
     public static AuthorizationBuilder Forbid(this AuthorizationBuilder builder, string action, IEnumerable<string> subjects, IEnumerable<string>? fields = null)
     {
         if (builder == null)

src/Privileged/AuthorizationContext.cs

@@ -1,12 +1,26 @@
 namespace Privileged;
 
-public class AuthorizationContext(IReadOnlyCollection<AuthorizationRule> rules, StringComparer? stringComparer = null)
+/// <summary>
+/// The authorization context used to check privileges
+/// </summary>
+/// <param name="rules">The authorization rules for this context</param>
+/// <param name="stringComparer">The <see cref="StringComparer"/> used for matching names</param>
+/// <seealso cref="Privileged.IAuthorizationContext" />
+public class AuthorizationContext(IReadOnlyCollection<AuthorizationRule> rules, StringComparer? stringComparer = null) : IAuthorizationContext
 {
+    /// <inheritdoc />
     public IReadOnlyCollection<AuthorizationRule> Rules { get; } = rules ?? throw new ArgumentNullException(nameof(rules));
 
+    /// <summary>
+    /// Gets the <see cref="StringComparer"/> used for matching names.
+    /// </summary>
+    /// <value>
+    /// The <see cref="StringComparer"/> used for matching names.
+    /// </value>
     public StringComparer StringComparer { get; } = stringComparer ?? StringComparer.InvariantCultureIgnoreCase;
 
 
+    /// <inheritdoc />
     public bool Authorized(string? action, string? subject, string? field = null)
     {
         if (action is null || subject is null)
@@ -26,8 +40,10 @@ public bool Authorized(string? action, string? subject, string? field = null)
         return state ?? false;
     }
 
+    /// <inheritdoc />
     public bool Unauthorized(string? action, string? subject, string? field = null) => !Authorized(action, subject, field);
 
+    /// <inheritdoc />
     public IEnumerable<AuthorizationRule> MatchRules(string? action, string? subject, string? field = null)
     {
         if (action is null || subject is null)

src/Privileged/AuthorizationRule.cs

@@ -1,5 +1,12 @@
 namespace Privileged;
 
+/// <summary>
+/// An authorization rule
+/// </summary>
+/// <param name="Action">The action to match for this rule</param>
+/// <param name="Subject">The subject to match for this rule</param>
+/// <param name="Fields">The field to match for this rule</param>
+/// <param name="Denied">true to make this a denied rule</param>
 public record AuthorizationRule(
     string Action,
     string Subject,

src/Privileged/AuthorizationSubjects.cs

@@ -1,6 +1,12 @@
 namespace Privileged;
 
+/// <summary>
+/// Authorization subject defaults
+/// </summary>
 public static class AuthorizationSubjects
 {
+    /// <summary>
+    /// Special keyword represents any subjects will be matched
+    /// </summary>
     public const string All = "all";
 }

src/Privileged/IAuthorizationContext.cs

@@ -0,0 +1,42 @@
+namespace Privileged;
+
+/// <summary>
+/// The authorization context definition used to check privileges
+/// </summary>
+public interface IAuthorizationContext
+{
+    /// <summary>
+    /// Gets the authorization rules for this context.
+    /// </summary>
+    /// <value>
+    /// The authorization rules for this context.
+    /// </value>
+    IReadOnlyCollection<AuthorizationRule> Rules { get; }
+
+    /// <summary>
+    /// Check if the specified <paramref name="action"/>, <paramref name="subject"/> and <paramref name="field"/> are authorized.
+    /// </summary>
+    /// <param name="action">The action to authorize.</param>
+    /// <param name="subject">The subject to authorize.</param>
+    /// <param name="field">The optional field to authorize.</param>
+    /// <returns>true if the specified <paramref name="action"/>, <paramref name="subject"/> and <paramref name="field"/> are authorized; otherwise false</returns>
+    bool Authorized(string? action, string? subject, string? field = null);
+
+    /// <summary>
+    /// Check if the specified <paramref name="action"/>, <paramref name="subject"/> and <paramref name="field"/> are unauthorized.
+    /// </summary>
+    /// <param name="action">The action to authorize.</param>
+    /// <param name="subject">The subject to authorize.</param>
+    /// <param name="field">The optional field to authorize.</param>
+    /// <returns>true if the specified <paramref name="action"/>, <paramref name="subject"/> and <paramref name="field"/> are unauthorized; otherwise false</returns>
+    bool Unauthorized(string? action, string? subject, string? field = null);
+
+    /// <summary>
+    /// Find the rules for the specified <paramref name="action"/>, <paramref name="subject"/> and <paramref name="field"/>
+    /// </summary>
+    /// <param name="action">The action to match.</param>
+    /// <param name="subject">The subject to match.</param>
+    /// <param name="field">The optional field to match.</param>
+    /// <returns>The rules for the specified <paramref name="action"/>, <paramref name="subject"/> and <paramref name="field"/></returns>
+    IEnumerable<AuthorizationRule> MatchRules(string? action, string? subject, string? field = null);
+}