Merge pull request #38 from mvSapphire/xmlDocumentation

Added xml documentation

src/PowerPipe.Extensions.MicrosoftDependencyInjection/PowerPipe.Extensions.MicrosoftDependencyInjection.csproj

@@ -12,6 +12,7 @@
         <PackageTags>pipeline, powerpipe, pipe, di, dependency injection</PackageTags>
         <PackageIcon>logo.png</PackageIcon>
         <PackageReadmeFile>README.md</PackageReadmeFile>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
     </PropertyGroup>
 
     <ItemGroup>

src/PowerPipe.Extensions.MicrosoftDependencyInjection/ServiceCollectionExtension.cs

@@ -5,8 +5,17 @@
 
 namespace PowerPipe.Extensions.MicrosoftDependencyInjection;
 
+/// <summary>
+/// Provides extension methods for configuring PowerPipe in Microsoft Dependency Injection (DI) services.
+/// </summary>
 public static class ServiceCollectionExtension
 {
+    /// <summary>
+    /// Adds PowerPipe services to the DI container with the specified lifetime.
+    /// </summary>
+    /// <param name="serviceCollection">The DI service collection to which services are added.</param>
+    /// <param name="lifetime">The lifetime of the added services (Transient, Scoped, or Singleton).</param>
+    /// <returns>The modified DI service collection.</returns>
     public static IServiceCollection AddPowerPipe(
         this IServiceCollection serviceCollection, ServiceLifetime lifetime = ServiceLifetime.Transient)
     {
@@ -19,6 +28,14 @@ public static IServiceCollection AddPowerPipe(
         };
     }
 
+    /// <summary>
+    /// Adds a PowerPipe step to the DI container with the specified lifetime.
+    /// </summary>
+    /// <typeparam name="TStep">The type of the step to add.</typeparam>
+    /// <typeparam name="TContext">The type of context used in the pipeline.</typeparam>
+    /// <param name="serviceCollection">The DI service collection to which the step is added.</param>
+    /// <param name="lifetime">The lifetime of the added step (Transient, Scoped, or Singleton).</param>
+    /// <returns>The modified DI service collection.</returns>
     public static IServiceCollection AddPowerPipeStep<TStep, TContext>(
         this IServiceCollection serviceCollection, ServiceLifetime lifetime = ServiceLifetime.Transient)
         where TStep : class, IStepBase<TContext>
@@ -33,6 +50,14 @@ public static IServiceCollection AddPowerPipeStep<TStep, TContext>(
         };
     }
 
+    /// <summary>
+    /// Adds a PowerPipe compensation step to the DI container with the specified lifetime.
+    /// </summary>
+    /// <typeparam name="TStep">The type of the compensation step to add.</typeparam>
+    /// <typeparam name="TContext">The type of context used in the pipeline.</typeparam>
+    /// <param name="serviceCollection">The DI service collection to which the compensation step is added.</param>
+    /// <param name="lifetime">The lifetime of the added compensation step (Transient, Scoped, or Singleton).</param>
+    /// <returns>The modified DI service collection.</returns>
     public static IServiceCollection AddPowerPipeCompensationStep<TStep, TContext>(
         this IServiceCollection serviceCollection, ServiceLifetime lifetime = ServiceLifetime.Transient)
         where TStep : class, IPipelineCompensationStep<TContext>

src/PowerPipe/Builder/PipelineBuilder.cs

@@ -5,6 +5,11 @@
 
 namespace PowerPipe.Builder;
 
+/// <summary>
+/// Represents a builder for creating a pipeline of steps.
+/// </summary>
+/// <typeparam name="TContext">The type of context used in the pipeline.</typeparam>
+/// <typeparam name="TResult">The type of result returned by the pipeline.</typeparam>
 public sealed class PipelineBuilder<TContext, TResult>
     where TContext : PipelineContext<TResult>
     where TResult : class
@@ -15,6 +20,11 @@ public sealed class PipelineBuilder<TContext, TResult>
     internal List<InternalStep<TContext>> Steps { get; } = new();
     private InternalStep<TContext> LastStep => Steps[^1];
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PipelineBuilder{TContext, TResult}"/> class.
+    /// </summary>
+    /// <param name="pipelineStepFactory">The factory for creating pipeline steps.</param>
+    /// <param name="context">The pipeline context.</param>
     public PipelineBuilder(IPipelineStepFactory pipelineStepFactory, TContext context)
     {
         ArgumentNullException.ThrowIfNull(pipelineStepFactory);
@@ -24,6 +34,11 @@ public PipelineBuilder(IPipelineStepFactory pipelineStepFactory, TContext contex
         _context = context;
     }
 
+    /// <summary>
+    /// Adds a step to the pipeline.
+    /// </summary>
+    /// <typeparam name="T">The type of step to add.</typeparam>
+    /// <returns>The current instance of the pipeline builder.</returns>
     public PipelineBuilder<TContext, TResult> Add<T>()
         where T : IStepBase<TContext>
     {
@@ -32,6 +47,12 @@ public PipelineBuilder<TContext, TResult> Add<T>()
         return this;
     }
 
+    /// <summary>
+    /// Adds a conditional step to the pipeline.
+    /// </summary>
+    /// <typeparam name="T">The type of step to add conditionally.</typeparam>
+    /// <param name="predicate">The predicate to determine whether to execute the step.</param>
+    /// <returns>The current instance of the pipeline builder.</returns>
     public PipelineBuilder<TContext, TResult> AddIf<T>(Predicate<TContext> predicate)
         where T : IStepBase<TContext>
     {
@@ -40,6 +61,13 @@ public PipelineBuilder<TContext, TResult> AddIf<T>(Predicate<TContext> predicate
         return this;
     }
 
+    /// <summary>
+    /// Adds an if-else conditional step to the pipeline.
+    /// </summary>
+    /// <typeparam name="TIf">The type of step to add if the predicate is true.</typeparam>
+    /// <typeparam name="TElse">The type of step to add if the predicate is false.</typeparam>
+    /// <param name="predicate">The predicate to determine whether to execute the if step.</param>
+    /// <returns>The current instance of the pipeline builder.</returns>
     public PipelineBuilder<TContext, TResult> AddIfElse<TIf, TElse>(Predicate<TContext> predicate)
         where TIf : IStepBase<TContext>
         where TElse : IStepBase<TContext>
@@ -52,6 +80,12 @@ public PipelineBuilder<TContext, TResult> AddIfElse<TIf, TElse>(Predicate<TConte
         return this;
     }
 
+    /// <summary>
+    /// Adds a conditional branch to the pipeline.
+    /// </summary>
+    /// <param name="predicate">The predicate to determine whether to execute the branch.</param>
+    /// <param name="action">An action to configure the branch.</param>
+    /// <returns>The current instance of the pipeline builder.</returns>
     public PipelineBuilder<TContext, TResult> If(
         Predicate<TContext> predicate, Func<PipelineBuilder<TContext, TResult>, PipelineBuilder<TContext, TResult>> action)
     {
@@ -62,6 +96,12 @@ public PipelineBuilder<TContext, TResult> If(
         return this;
     }
 
+    /// <summary>
+    /// Adds a parallel execution branch to the pipeline.
+    /// </summary>
+    /// <param name="action">An action to configure the parallel execution branch.</param>
+    /// <param name="maxDegreeOfParallelism">The maximum degree of parallelism for the branch.</param>
+    /// <returns>The current instance of the pipeline builder.</returns>
     public PipelineBuilder<TContext, TResult> Parallel(
         Func<PipelineBuilder<TContext, TResult>, PipelineBuilder<TContext, TResult>> action, int maxDegreeOfParallelism = -1)
     {
@@ -72,6 +112,14 @@ public PipelineBuilder<TContext, TResult> Parallel(
         return this;
     }
 
+    /// <summary>
+    /// Configures error handling for the last added step.
+    /// </summary>
+    /// <param name="errorHandling">The error handling behavior to configure.</param>
+    /// <param name="retryInterval">The retry interval for retrying the step in case of an error.</param>
+    /// <param name="maxRetryCount">The maximum number of times to retry the step.</param>
+    /// <param name="predicate">A predicate to determine whether error handling should be applied.</param>
+    /// <returns>The current instance of the pipeline builder.</returns>
     public PipelineBuilder<TContext, TResult> OnError(PipelineStepErrorHandling errorHandling,
         TimeSpan? retryInterval = null, int? maxRetryCount = null, Predicate<TContext> predicate = null)
     {
@@ -80,6 +128,11 @@ public PipelineBuilder<TContext, TResult> OnError(PipelineStepErrorHandling erro
         return this;
     }
 
+    /// <summary>
+    /// Adds a compensation step to the last added step in the pipeline.
+    /// </summary>
+    /// <typeparam name="T">The type of compensation step to add.</typeparam>
+    /// <returns>The current instance of the pipeline builder.</returns>
     public PipelineBuilder<TContext, TResult> CompensateWith<T>()
         where T : IPipelineCompensationStep<TContext>
     {
@@ -88,6 +141,10 @@ public PipelineBuilder<TContext, TResult> CompensateWith<T>()
         return this;
     }
 
+    /// <summary>
+    /// Builds the pipeline based on the configured steps.
+    /// </summary>
+    /// <returns>The constructed pipeline.</returns>
     public IPipeline<TResult> Build()
     {
         Steps.Add(new FinishStep<TContext>());

src/PowerPipe/Builder/Steps/AddIfElseStep.cs

@@ -5,19 +5,35 @@
 
 namespace PowerPipe.Builder.Steps;
 
+/// <summary>
+/// Represents a pipeline step that conditionally executes one of two sub-steps based on a provided predicate.
+/// </summary>
+/// <typeparam name="TContext">The type of context used in the pipeline.</typeparam>
 internal class AddIfElseStep<TContext> : InternalStep<TContext>
 {
     private readonly IPipelineStep<TContext> _ifStep;
     private readonly IPipelineStep<TContext> _elseStep;
     private readonly Predicate<TContext> _predicate;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AddIfElseStep{TContext}"/> class.
+    /// </summary>
+    /// <param name="predicate">The predicate to determine which sub-step to execute.</param>
+    /// <param name="ifStep">The sub-step to execute if the predicate is true.</param>
+    /// <param name="elseStep">The sub-step to execute if the predicate is false.</param>
     internal AddIfElseStep(Predicate<TContext> predicate, IPipelineStep<TContext> ifStep, IPipelineStep<TContext> elseStep)
     {
         _predicate = predicate;
         _ifStep = ifStep;
         _elseStep = elseStep;
     }
 
+    /// <summary>
+    /// Executes the if-else step asynchronously based on the provided context and predicate.
+    /// </summary>
+    /// <param name="context">The context on which the if-else step operates.</param>
+    /// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     protected override async Task ExecuteInternalAsync(TContext context, CancellationToken cancellationToken)
     {
         StepExecuted = true;

src/PowerPipe/Builder/Steps/AddIfStep.cs

@@ -5,17 +5,32 @@
 
 namespace PowerPipe.Builder.Steps;
 
+/// <summary>
+/// Represents a pipeline step that conditionally executes a sub-step based on a provided predicate.
+/// </summary>
+/// <typeparam name="TContext">The type of context used in the pipeline.</typeparam>
 internal class AddIfStep<TContext> : InternalStep<TContext>
 {
     private readonly IPipelineStep<TContext> _step;
     private readonly Predicate<TContext> _predicate;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AddIfStep{TContext}"/> class.
+    /// </summary>
+    /// <param name="predicate">The predicate to determine whether to execute the sub-step.</param>
+    /// <param name="step">The sub-step to execute if the predicate is true.</param>
     internal AddIfStep(Predicate<TContext> predicate, IPipelineStep<TContext> step)
     {
         _predicate = predicate;
         _step = step;
     }
 
+    /// <summary>
+    /// Executes the if step asynchronously based on the provided context and predicate.
+    /// </summary>
+    /// <param name="context">The context on which the if step operates.</param>
+    /// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     protected override async Task ExecuteInternalAsync(TContext context, CancellationToken cancellationToken)
     {
         if (_predicate(context))

src/PowerPipe/Builder/Steps/CompensationStep.cs

@@ -5,12 +5,23 @@
 
 namespace PowerPipe.Builder.Steps;
 
+/// <summary>
+/// Represents a compensation step used in pipeline processing to perform compensation actions.
+/// </summary>
+/// <typeparam name="TContext">The type of context used in the pipeline.</typeparam>
 internal class CompensationStep<TContext> : IPipelineCompensationStep<TContext>
 {
     private readonly Lazy<IPipelineCompensationStep<TContext>> _step;
 
+    /// <summary>
+    /// Gets a value indicating whether the compensation step has been executed.
+    /// </summary>
     public bool IsCompensated { get; private set; }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CompensationStep{TContext}"/> class.
+    /// </summary>
+    /// <param name="factory">A factory function to create the compensation step.</param>
     internal CompensationStep(Func<IPipelineCompensationStep<TContext>> factory)
     {
         _step = new Lazy<IPipelineCompensationStep<TContext>>(() =>
@@ -20,6 +31,12 @@ internal CompensationStep(Func<IPipelineCompensationStep<TContext>> factory)
         });
     }
 
+    /// <summary>
+    /// Performs compensation actions asynchronously.
+    /// </summary>
+    /// <param name="context">The context on which the compensation action is performed.</param>
+    /// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous compensation operation.</returns>
     public async Task CompensateAsync(TContext context, CancellationToken cancellationToken)
     {
         IsCompensated = true;

src/PowerPipe/Builder/Steps/FinishStep.cs

@@ -1,5 +1,9 @@
 namespace PowerPipe.Builder.Steps;
 
+/// <summary>
+/// Represents a finishing step in the pipeline.
+/// </summary>
+/// <typeparam name="TContext">The type of context used in the pipeline.</typeparam>
 internal class FinishStep<TContext> : InternalStep<TContext>
 {
 }

src/PowerPipe/Builder/Steps/IfPipelineStep.cs

@@ -4,19 +4,35 @@
 
 namespace PowerPipe.Builder.Steps;
 
+/// <summary>
+/// Represents a conditional pipeline step that executes a sub-pipeline based on a provided predicate.
+/// </summary>
+/// <typeparam name="TContext">The type of context used in the pipeline.</typeparam>
+/// <typeparam name="TResult">The type of result returned by the sub-pipeline.</typeparam>
 internal class IfPipelineStep<TContext, TResult> : InternalStep<TContext>
     where TContext : PipelineContext<TResult>
     where TResult : class
 {
     private readonly Predicate<TContext> _predicate;
     private readonly PipelineBuilder<TContext, TResult> _pipelineBuilder;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="IfPipelineStep{TContext, TResult}"/> class.
+    /// </summary>
+    /// <param name="predicate">The predicate to determine whether to execute the sub-pipeline.</param>
+    /// <param name="pipelineBuilder">The builder for the sub-pipeline to execute.</param>
     public IfPipelineStep(Predicate<TContext> predicate, PipelineBuilder<TContext, TResult> pipelineBuilder)
     {
         _predicate = predicate;
         _pipelineBuilder = pipelineBuilder;
     }
 
+    /// <summary>
+    /// Executes the conditional pipeline step asynchronously based on the provided context and predicate.
+    /// </summary>
+    /// <param name="context">The context on which the conditional pipeline step operates.</param>
+    /// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     protected override async Task ExecuteInternalAsync(TContext context, CancellationToken cancellationToken)
     {
         if (_predicate(context))