Addressed review feedback

Author: Bart Koelman

src/JsonApiDotNetCore/Middleware/OperationKind.cs

@@ -1,7 +1,7 @@
 namespace JsonApiDotNetCore.Middleware
 {
     /// <summary>
-    /// Lists the functional operation kinds from a resource request or an atomic:operations request.
+    /// Lists the functional operation kinds of a resource request or an atomic:operations request.
     /// </summary>
     public enum OperationKind
     {

src/JsonApiDotNetCore/Repositories/EntityFrameworkCoreRepository.cs

@@ -173,7 +173,7 @@ public virtual async Task CreateAsync(TResource resourceFromRequest, TResource r
             {
                 object rightResources = relationship.GetValue(resourceFromRequest);
 
-                object rightResourcesEdited = await EditRelationshipAsync(resourceForDatabase, relationship, rightResources, OperationKind.CreateResource,
+                object rightResourcesEdited = await VisitSetRelationshipAsync(resourceForDatabase, relationship, rightResources, OperationKind.CreateResource,
                     cancellationToken);
 
                 await UpdateRelationshipAsync(relationship, resourceForDatabase, rightResourcesEdited, collector, cancellationToken);
@@ -194,7 +194,7 @@ public virtual async Task CreateAsync(TResource resourceFromRequest, TResource r
             await _resourceDefinitionAccessor.OnWriteSucceededAsync(resourceForDatabase, OperationKind.CreateResource, cancellationToken);
         }
 
-        private async Task<object> EditRelationshipAsync(TResource leftResource, RelationshipAttribute relationship, object rightResourceIds,
+        private async Task<object> VisitSetRelationshipAsync(TResource leftResource, RelationshipAttribute relationship, object rightResourceIds,
             OperationKind operationKind, CancellationToken cancellationToken)
         {
             if (relationship is HasOneAttribute hasOneRelationship)
@@ -241,7 +241,7 @@ public virtual async Task UpdateAsync(TResource resourceFromRequest, TResource r
             {
                 object rightResources = relationship.GetValue(resourceFromRequest);
 
-                object rightResourcesEdited = await EditRelationshipAsync(resourceFromDatabase, relationship, rightResources, OperationKind.UpdateResource,
+                object rightResourcesEdited = await VisitSetRelationshipAsync(resourceFromDatabase, relationship, rightResources, OperationKind.UpdateResource,
                     cancellationToken);
 
                 AssertIsNotClearingRequiredRelationship(relationship, resourceFromDatabase, rightResourcesEdited);
@@ -392,7 +392,7 @@ public virtual async Task SetRelationshipAsync(TResource primaryResource, object
             RelationshipAttribute relationship = _targetedFields.Relationships.Single();
 
             object secondaryResourceIdsEdited =
-                await EditRelationshipAsync(primaryResource, relationship, secondaryResourceIds, OperationKind.SetRelationship, cancellationToken);
+                await VisitSetRelationshipAsync(primaryResource, relationship, secondaryResourceIds, OperationKind.SetRelationship, cancellationToken);
 
             AssertIsNotClearingRequiredRelationship(relationship, primaryResource, secondaryResourceIdsEdited);
 

src/JsonApiDotNetCore/Resources/IResourceDefinition.cs

@@ -158,7 +158,7 @@ public interface IResourceDefinition<TResource, TId>
         Task OnPrepareWriteAsync(TResource resource, OperationKind operationKind, CancellationToken cancellationToken);
 
         /// <summary>
-        /// Executes before replacing (overwriting) a to-one relationship.
+        /// Executes before setting (or clearing) the resource at the right side of a to-one relationship.
         /// <para>
         /// Implementing this method enables to perform validations and change <paramref name="rightResourceId" />, before the relationship is updated.
         /// </para>
@@ -167,10 +167,10 @@ public interface IResourceDefinition<TResource, TId>
         /// The original resource retrieved from the underlying data store, that declares <paramref name="hasOneRelationship" />.
         /// </param>
         /// <param name="hasOneRelationship">
-        /// The to-one relationship being replaced or cleared.
+        /// The to-one relationship being set.
         /// </param>
         /// <param name="rightResourceId">
-        /// The replacement resource identifier (or <c>null</c> to clear the relationship), coming from the request.
+        /// The new resource identifier (or <c>null</c> to clear the relationship), coming from the request.
         /// </param>
         /// <param name="operationKind">
         /// Identifies from which endpoint this method was called. Possible values: <see cref="OperationKind.CreateResource" />,
@@ -180,13 +180,13 @@ public interface IResourceDefinition<TResource, TId>
         /// Propagates notification that request handling should be canceled.
         /// </param>
         /// <returns>
-        /// The replacement resource identifier, or <c>null</c> to clear the relationship.
+        /// The replacement resource identifier, or <c>null</c> to clear the relationship. Returns <paramref name="rightResourceId" /> by default.
         /// </returns>
         Task<IIdentifiable> OnSetToOneRelationshipAsync(TResource leftResource, HasOneAttribute hasOneRelationship, IIdentifiable rightResourceId,
             OperationKind operationKind, CancellationToken cancellationToken);
 
         /// <summary>
-        /// Executes before replacing (overwriting) a to-many relationship.
+        /// Executes before setting the resources at the right side of a to-many relationship. This replaces on existing set.
         /// <para>
         /// Implementing this method enables to perform validations and make changes to <paramref name="rightResourceIds" />, before the relationship is updated.
         /// </para>
@@ -195,7 +195,7 @@ Task<IIdentifiable> OnSetToOneRelationshipAsync(TResource leftResource, HasOneAt
         /// The original resource retrieved from the underlying data store, that declares <paramref name="hasManyRelationship" />.
         /// </param>
         /// <param name="hasManyRelationship">
-        /// The to-many relationship being replaced.
+        /// The to-many relationship being set.
         /// </param>
         /// <param name="rightResourceIds">
         /// The set of resource identifiers to replace any existing set with, coming from the request.
@@ -211,7 +211,7 @@ Task OnSetToManyRelationshipAsync(TResource leftResource, HasManyAttribute hasMa
             OperationKind operationKind, CancellationToken cancellationToken);
 
         /// <summary>
-        /// Executes before adding resources to a to-many relationship, as part of a POST relationship request.
+        /// Executes before adding resources to the right side of a to-many relationship, as part of a POST relationship request.
         /// <para>
         /// Implementing this method enables to perform validations and make changes to <paramref name="rightResourceIds" />, before the relationship is updated.
         /// </para>
@@ -232,7 +232,7 @@ Task OnAddToRelationshipAsync(TId leftResourceId, HasManyAttribute hasManyRelati
             CancellationToken cancellationToken);
 
         /// <summary>
-        /// Executes before removing resources from a to-many relationship, as part of a DELETE relationship request.
+        /// Executes before removing resources from the right side of a to-many relationship, as part of a DELETE relationship request.
         /// <para>
         /// Implementing this method enables to perform validations and make changes to <paramref name="rightResourceIds" />, before the relationship is updated.
         /// </para>