Adding documentation comments to EF extensions and utilities projects.

Author: codepb

src/DDDToolkit.EntityFramework.Extensions/DDDToolkit.EntityFramework.Extensions.csproj

@@ -16,8 +16,12 @@
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
   </PropertyGroup>
 
+  <PropertyGroup>
+    <DocumentationFile>C:\Users\paulj\source\repos\DDDToolkit\src\DDDToolkit.EntityFramework.Extensions\DDDToolkit.EntityFramework.Extensions.xml</DocumentationFile>
+  </PropertyGroup>
+
   <ItemGroup>
-    <None Include="..\..\LICENSE" Pack="true" PackagePath=""/>
+    <None Include="..\..\LICENSE" Pack="true" PackagePath="" />
   </ItemGroup>
 
   <ItemGroup>

src/DDDToolkit.EntityFramework.Extensions/DDDToolkit.EntityFramework.Extensions.xml

@@ -1,16 +1,35 @@
 using DDDToolkit.Core;
 using DDDToolkit.Core.Interfaces;
 using Microsoft.EntityFrameworkCore;
-using Microsoft.EntityFrameworkCore.Query;
 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Reflection;
 
 namespace DDDToolkit.EntityFramework.Extensions
 {
+    /// <summary>
+    /// Extensions to include properties in Entity Framework.
+    /// </summary>
     public static class IncludeExtensions
     {
+        /// <summary>
+        /// <para>
+        /// Include every navigation property on the entity.
+        /// Navigate through every property that can be included, includes it,
+        /// then recursively repeats the operation for all children until the
+        /// whole property tree is included.
+        /// </para>
+        /// <para>
+        /// Note: do not use this if there are any cyclical references. Due to
+        /// the recursive nature, this will cause a stack overflow.
+        /// </para>
+        /// </summary>
+        /// <typeparam name="T">The type of entity.</typeparam>
+        /// <param name="source">The Queryable to operate on.</param>
+        /// <returns>A new Queryable with all child properties included in the Entity Framework query.</returns>
+        /// <exception cref="StackOverflowException">Thrown when there is a cyclic reference on the
+        /// entity, or any child entity.</exception>
         public static IQueryable<T> IncludeEverything<T>(this IQueryable<T> source) where T : class
         {
             var type = source.GetType();

src/DDDToolkit.EntityFramework.Extensions/IncludeExtensions.cs

@@ -1,16 +1,24 @@
 using DDDToolkit.Utilities.Extensions;
 using Microsoft.EntityFrameworkCore;
-using System;
 using System.Collections.Generic;
 using System.Linq;
-using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
 
 namespace DDDToolkit.EntityFramework.Extensions
 {
+    /// <summary>
+    /// Extensions on Queryables
+    /// </summary>
     public static class QueryableExtensions
     {
+        /// <summary>
+        /// Converts a Queryable to a <see cref="IReadOnlyCollection{T}"/>.
+        /// </summary>
+        /// <typeparam name="T">The type of entity for the IQueryable.</typeparam>
+        /// <param name="queryable">The IQueryable to convert.</param>
+        /// <param name="cancellationToken">A cancellation token to use for the operation.</param>
+        /// <returns>A Task returning a <see cref="IReadOnlyCollection{T}"/> from the IQueryable.</returns>
         public static Task<IReadOnlyCollection<T>> ToReadOnlyCollectionAsync<T>(this IQueryable<T> queryable, CancellationToken cancellationToken = default(CancellationToken))
             => queryable.ToListAsync(cancellationToken).ToReadOnlyCollection();
     }

src/DDDToolkit.EntityFramework.Extensions/QueryableExtensions.cs

@@ -16,8 +16,12 @@
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
   </PropertyGroup>
 
+  <PropertyGroup>
+    <DocumentationFile>C:\Users\paulj\source\repos\DDDToolkit\src\DDDToolkit.Utilities\DDDToolkit.Utilities.xml</DocumentationFile>
+  </PropertyGroup>
+
   <ItemGroup>
-    <None Include="..\..\LICENSE" Pack="true" PackagePath=""/>
+    <None Include="..\..\LICENSE" Pack="true" PackagePath="" />
   </ItemGroup>
 
 </Project>

src/DDDToolkit.Utilities/DDDToolkit.Utilities.csproj

@@ -4,25 +4,55 @@
 
 namespace DDDToolkit.Utilities.Extensions
 {
+    /// <summary>
+    /// Extensions to Tasks.
+    /// </summary>
     public static class TaskExtensions
     {
+        /// <summary>
+        /// Coverts a Task of a <see cref="List{T}"/> to a Task of a <see cref="IReadOnlyCollection{T}"/>.
+        /// </summary>
+        /// <typeparam name="T">The type of entity in the List.</typeparam>
+        /// <param name="task">The tssk to convert.</param>
+        /// <returns>The Task of a List converted to a Task of a IReadOnlyCollection.</returns>
         public static Task<IReadOnlyCollection<T>> ToReadOnlyCollection<T>(this Task<List<T>> task)
             => task.ContinueWith(t => t.Result.AsReadOnly()).ConvertTask().ToTaskOf<IReadOnlyCollection<T>>();
 
+        /// <summary>
+        /// Begin converting a Task of a type to a Task of a compatiable type.
+        /// </summary>
+        /// <typeparam name="T">The current type of the Task.</typeparam>
+        /// <param name="task">The Task to convert.</param>
+        /// <returns>A <see cref="TaskConverter{T}"/> which enables selecting a Task to convert to.</returns>
         public static TaskConverter<T> ConvertTask<T>(this Task<T> task)
         {
             return new TaskConverter<T>(task);
         }
 
+        /// <summary>
+        /// A class that can convert a Task of one type, to a Task of a compatible type.
+        /// </summary>
+        /// <typeparam name="T">The current type of the Task.</typeparam>
         public class TaskConverter<T>
         {
             private Task<T> _task;
 
+            /// <summary>
+            /// Initialises a Task converter that will be able to convert
+            /// the supplied Task to a Task of a compatible type.
+            /// </summary>
+            /// <param name="task">The Task to convert.</param>
             public TaskConverter(Task<T> task)
             {
                 _task = task;
             }
 
+            /// <summary>
+            /// Creates and returns a new Task of the type specified from the
+            /// Task that was supplied to the class.
+            /// </summary>
+            /// <typeparam name="TResult">The type to convert the Task to.</typeparam>
+            /// <returns>A new Task of the type supplied.</returns>
             public Task<TResult> ToTaskOf<TResult>()
                 where TResult : class
             {
@@ -33,6 +63,17 @@ public Task<TResult> ToTaskOf<TResult>()
                 return _task.ContinueWith(t => t.Result as TResult);
             }
 
+            /// <summary>
+            /// <para>
+            /// Creates and returns a new Task of the type specified from the
+            /// Task that was supplied to the class.
+            /// </para>
+            /// <para>
+            /// An alias for <see cref="ToTaskOf{TResult}"/>
+            /// </para>
+            /// </summary>
+            /// <typeparam name="TResult">The type to convert the Task to.</typeparam>
+            /// <returns>A new Task of the type supplied.</returns>
             public Task<TResult> To<TResult>()
                 where TResult : class
                 => ToTaskOf<TResult>();