comments: documentation in code

Author: maurei

src/JsonApiDotNetCore/Hooks/Discovery/IncludeDatabaseValues.cs

@@ -1,5 +1,5 @@
 using System;
-namespace JsonApiDotNetCore.Hooks.Discovery
+namespace JsonApiDotNetCore.Hooks
 {
     public class IncludeDatabaseValues : Attribute
     {

src/JsonApiDotNetCore/Hooks/Execution/EntityDiff.cs

@@ -1,11 +1,18 @@
-using System;
+
 using System.Collections;
 using System.Collections.Generic;
-using JsonApiDotNetCore.Internal;
 using JsonApiDotNetCore.Models;
 
 namespace JsonApiDotNetCore.Hooks
 {
+    /// <summary>
+    /// A helper class that provides insight in what is to be updated. The 
+    /// <see cref="IEntityDiff{TEntity}.RequestEntities"/> property reflects what was parsed from the incoming request,
+    /// where the <see cref="IEntityDiff{TEntity}.DatabaseEntities"/> reflects what is the current state in the database.
+    /// 
+    /// Any relationships that are updated can be retrieved via the methods implemented on 
+    /// <see cref="IUpdatedRelationshipHelper{TDependent}"/>.
+    /// </summary>
     public interface IEntityDiff<TEntity> : IUpdatedRelationshipHelper<TEntity> where TEntity : class, IIdentifiable
     {
         HashSet<TEntity> RequestEntities { get; }

src/JsonApiDotNetCore/Hooks/Execution/HookExecutorHelper.cs

@@ -13,7 +13,7 @@
 using Microsoft.EntityFrameworkCore;
 using JsonApiDotNetCore.Services;
 
-namespace JsonApiDotNetCore.Internal
+namespace JsonApiDotNetCore.Hooks
 {
     /// <inheritdoc/>
     internal class HookExecutorHelper : IHookExecutorHelper

src/JsonApiDotNetCore/Hooks/Execution/IHookExecutorHelper.cs

@@ -2,14 +2,14 @@
 using System.Collections;
 using System.Collections.Generic;
 using JsonApiDotNetCore.Models;
-using JsonApiDotNetCore.Hooks;
 
-namespace JsonApiDotNetCore.Internal
+namespace JsonApiDotNetCore.Hooks
 {
     /// <summary>
-    /// A helper class that retrieves all metadata required for the hook 
-    /// executor to call resource hooks.  It gets RelationshipAttributes, 
-    /// ResourceHookContainers and figures out wether hooks are actually implemented.
+    /// A helper class for retrieving meta data about hooks, 
+    /// fetching database values and performing other recurring internal operations.
+    /// 
+    /// Used internalyl by <see cref="ResourceHookExecutor"/>
     /// </summary>
     internal interface IHookExecutorHelper
     {
@@ -21,10 +21,8 @@ internal interface IHookExecutorHelper
         /// Also caches the retrieves containers so we don't need to reflectively
         /// instantiate them multiple times.
         /// </summary>
-        /// <returns>The resource definition.</returns>
-        /// <param name="targetEntity">Target entity type</param>
-        /// <param name="hook">The hook to get a ResourceDefinition for.</param>
         IResourceHookContainer GetResourceHookContainer(Type targetEntity, ResourceHook hook = ResourceHook.None);
+
         /// <summary>
         /// For a particular ResourceHook and for a given model type, checks if 
         /// the ResourceDefinition has an implementation for the hook
@@ -33,13 +31,17 @@ internal interface IHookExecutorHelper
         /// Also caches the retrieves containers so we don't need to reflectively
         /// instantiate them multiple times.
         /// </summary>
-        /// <returns>The resource definition.</returns>
-        /// <typeparam name="TEntity">Target entity type</typeparam>
-        /// <param name="hook">The hook to get a ResourceDefinition for.</param>
         IResourceHookContainer<TEntity> GetResourceHookContainer<TEntity>(ResourceHook hook = ResourceHook.None) where TEntity : class, IIdentifiable;
 
+        /// <summary>
+        /// Load the implicitly affected entities from the database for a given set of target target entities and involved relationships
+        /// </summary>
+        /// <returns>The implicitly affected entities by relationship</returns>
         Dictionary<RelationshipProxy, IEnumerable> LoadImplicitlyAffected(Dictionary<RelationshipProxy, IEnumerable> principalEntities, IEnumerable existingDependentEntities = null);
 
+        /// <summary>
+        /// For a set of entities, loads current values from the database
+        /// </summary>
         IEnumerable LoadDbValues(Type entityType, IEnumerable entities, ResourceHook hook, params RelationshipProxy[] relationships);
         HashSet<TEntity> LoadDbValues<TEntity>(IEnumerable<TEntity> entities, ResourceHook hook, params RelationshipProxy[] relationships) where TEntity : class, IIdentifiable;
     }

src/JsonApiDotNetCore/Hooks/Execution/UpdatedRelationshipHelper.cs

@@ -2,17 +2,28 @@
 using System.Collections;
 using System.Collections.Generic;
 using System.Linq;
-using JsonApiDotNetCore.Internal;
 using JsonApiDotNetCore.Models;
 
 namespace JsonApiDotNetCore.Hooks
 {
     public interface IUpdatedRelationshipHelper { }
 
+    /// <summary>
+    /// A helper class that provides insights in which relationships have been updated for which entities.
+    /// </summary>
     public interface IUpdatedRelationshipHelper<TDependent> : IUpdatedRelationshipHelper where TDependent : class, IIdentifiable
     {
+        /// <summary>
+        /// Gets a dictionary of all entities grouped by affected relationship.
+        /// </summary>
         Dictionary<RelationshipAttribute, HashSet<TDependent>> AllEntitiesByRelation { get; }
+        /// <summary>
+        /// Gets a dictionary of all entities that have an affected relationship to type <typeparamref name="TPrincipal"/>
+        /// </summary>
         Dictionary<RelationshipAttribute, HashSet<TDependent>> EntitiesRelatedTo<TPrincipal>() where TPrincipal : class, IIdentifiable;
+        /// <summary>
+        /// Gets a dictionary of all entities that have an affected relationship to type <paramref name="principalType"/>
+        /// </summary>
         Dictionary<RelationshipAttribute, HashSet<TDependent>> EntitiesRelatedTo(Type principalType);
     }