From bc419a49bd32054202566df83fbef0db11d095a8 Mon Sep 17 00:00:00 2001
From: Thomas Rittson <trittson@bitwarden.com>
Date: Mon, 7 Oct 2024 13:01:58 +1000
Subject: [PATCH] Tweak comments

---
 .../Policies/IPolicyDefinition.cs                   | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/src/Core/AdminConsole/OrganizationFeatures/Policies/IPolicyDefinition.cs b/src/Core/AdminConsole/OrganizationFeatures/Policies/IPolicyDefinition.cs
index 5b1229ff77..c3bbf6bfc5 100644
--- a/src/Core/AdminConsole/OrganizationFeatures/Policies/IPolicyDefinition.cs
+++ b/src/Core/AdminConsole/OrganizationFeatures/Policies/IPolicyDefinition.cs
@@ -5,22 +5,26 @@ using Bit.Core.AdminConsole.Enums;
 
 namespace Bit.Core.AdminConsole.OrganizationFeatures.Policies;
 
+/// <summary>
+/// Defines behavior and functionality for a given PolicyType.
+/// </summary>
 public interface IPolicyDefinition
 {
     /// <summary>
-    /// The PolicyType that the strategy is responsible for handling.
+    /// The PolicyType that this definition relates to.
     /// </summary>
     public PolicyType Type { get; }
 
     /// <summary>
     /// PolicyTypes that must be enabled before this policy can be enabled, if any.
+    /// These dependencies will be checked when this policy is enabled and when any required policy is disabled.
     /// </summary>
     public IEnumerable<PolicyType> RequiredPolicies => [];
 
     /// <summary>
     /// Validates a policy before saving it.
-    /// Basic interdependencies between policies are already handled by the <see cref="RequiredPolicies"/> definition.
-    /// Use this for additional or more complex validation, if any.
+    /// Do not use this for simple dependencies between different policies - see <see cref="RequiredPolicies"/> instead.
+    /// Implementation is optional; by default it will not perform any validation.
     /// </summary>
     /// <param name="currentPolicy">The current policy, if any</param>
     /// <param name="modifiedPolicy">The modified policy to be saved</param>
@@ -28,8 +32,9 @@ public interface IPolicyDefinition
     public Task<string?> ValidateAsync(Policy? currentPolicy, Policy modifiedPolicy) => Task.FromResult<string?>(null);
 
     /// <summary>
-    /// Optionally performs side effects after a policy is validated but before it is saved.
+    /// Performs side effects after a policy is validated but before it is saved.
     /// For example, this can be used to remove non-compliant users from the organization.
+    /// Implementation is optional; by default it will not perform any side effects.
     /// </summary>
     /// <param name="currentPolicy">The current policy, if any</param>
     /// <param name="modifiedPolicy">The modified policy to be saved</param>