Generate documentation file from the XML source code. (#38)

* Generate documentation file from the XML source code.

nuspec/XPing365.Availability.nuspec

@@ -32,5 +32,6 @@
     <file src="README.md" target="docs" />
     <file src="..\docs\images\icon.png" target="images\" />
     <file src="..\src\XPing365.Sdk.Availability\bin\Release\net8.0\XPing365.Sdk.Availability.dll" target="lib\net8.0\XPing365.Sdk.Availability.dll" />
+    <file src="..\src\XPing365.Sdk.Availability\bin\Release\net8.0\XPing365.Sdk.Availability.xml" target="lib\net8.0\XPing365.Sdk.Availability.xml" />
   </files>
 </package>

nuspec/XPing365.Core.nuspec

@@ -30,5 +30,6 @@
     <file src="README.md" target="docs" />
     <file src="..\docs\images\icon.png" target="images\" />
     <file src="..\src\XPing365.Sdk.Core\bin\Release\net8.0\XPing365.Sdk.Core.dll" target="lib\net8.0\XPing365.Sdk.Core.dll" />
+    <file src="..\src\XPing365.Sdk.Core\bin\Release\net8.0\XPing365.Sdk.Core.xml" target="lib\net8.0\XPing365.Sdk.Core.xml" />
   </files>
 </package>

src/XPing365.Sdk.Availability/TestActions/DnsLookup.cs

@@ -14,14 +14,20 @@ namespace XPing365.Sdk.Availability.TestActions;
 /// </summary>
 public sealed class DnsLookup() : TestComponent(name: StepName, type: TestStepType.ActionStep)
 {
+    /// <summary>
+    /// The name of the test component that represents a DnsLookup test operation.
+    /// </summary>
+    /// <remarks>
+    /// This constant is used to register the DnsLookup class in the test framework.
+    /// </remarks>
     public const string StepName = "DNS lookup";
 
     /// <summary>
     /// This method performs the test step operation asynchronously.
     /// </summary>
     /// <param name="url">A Uri object that represents the URL of the page being validated.</param>
     /// <param name="settings">A <see cref="TestSettings"/> object that contains the settings for the test.</param>
-    /// <param name="session">A <see cref="TestContext"/> object that represents the test session.</param>
+    /// <param name="context">A <see cref="TestContext"/> object that represents the test context.</param>
     /// <param name="serviceProvider">An instance object of a mechanism for retrieving a service object.</param>
     /// <param name="cancellationToken">An optional CancellationToken object that can be used to cancel the 
     /// this operation.</param>

src/XPing365.Sdk.Availability/TestActions/HttpRequestSender.cs

@@ -33,18 +33,24 @@ namespace XPing365.Sdk.Availability.TestActions;
 /// separate testing pipelines, one for each client type, and run them independently.
 /// </note>
 /// </remarks>
-public class HttpRequestSender(Client client = Client.HttpClient) : 
+public class HttpRequestSender(Client client = Client.HttpClient) :
     TestComponent(name: StepName, type: TestStepType.ActionStep)
 {
     private readonly Lazy<HttpClientRequestSender> _httpClientRequestSender = new(
-        valueFactory: () => new HttpClientRequestSender($"{StepName} ({nameof(Client.HttpClient)})"), 
+        valueFactory: () => new HttpClientRequestSender($"{StepName} ({nameof(Client.HttpClient)})"),
         isThreadSafe: true);
     private readonly Lazy<HeadlessBrowserRequestSender> _headlessBrowserRequestSender = new(
-        valueFactory: () => new HeadlessBrowserRequestSender($"{StepName} ({nameof(Client.HeadlessBrowser)})"), 
+        valueFactory: () => new HeadlessBrowserRequestSender($"{StepName} ({nameof(Client.HeadlessBrowser)})"),
         isThreadSafe: true);
-    
+
     private readonly Client _client = client;
 
+    /// <summary>
+    /// The name of the test component that represents a HttpRequestSender test operation.
+    /// </summary>
+    /// <remarks>
+    /// This constant is used to register the HttpRequestSender class in the test framework.
+    /// </remarks>
     public const string StepName = "Http request sender";
 
     /// <summary>

src/XPing365.Sdk.Availability/TestActions/IPAddressAccessibilityCheck.cs

@@ -18,14 +18,20 @@ namespace XPing365.Sdk.Availability.TestActions;
 /// </summary>
 public sealed class IPAddressAccessibilityCheck() : TestComponent(name: StepName, type: TestStepType.ActionStep)
 {
+    /// <summary>
+    /// The name of the test component that represents a IPAddressAccessibilityCheck of tests.
+    /// </summary>
+    /// <remarks>
+    /// This constant is used to register the IPAddressAccessibilityCheck class in the test framework.
+    /// </remarks>
     public const string StepName = "IPAddress accessibility check";
 
     /// <summary>
     /// This method performs the test step operation asynchronously.
     /// </summary>
     /// <param name="url">A Uri object that represents the URL of the page being validated.</param>
     /// <param name="settings">A <see cref="TestSettings"/> object that contains the settings for the test.</param>
-    /// <param name="session">A <see cref="TestContext"/> object that represents the test session.</param>
+    /// <param name="context">A <see cref="TestContext"/> object that represents the test context.</param>
     /// <param name="serviceProvider">An instance object of a mechanism for retrieving a service object.</param>
     /// <param name="cancellationToken">An optional CancellationToken object that can be used to cancel the 
     /// this operation.</param>

src/XPing365.Sdk.Availability/TestActions/Internals/HttpClientRequestSender.cs

@@ -15,8 +15,7 @@ namespace XPing365.Sdk.Availability.TestActions.Internals;
 /// <see cref="HttpClient"/> class, which is used to send the HTTP request.
 /// </summary>
 /// <remarks>
-/// Before using this test component, you need to register the necessary services by calling the 
-/// <see cref="DependencyInjectionExtension.AddHttpClients(IServiceCollection, Action{IServiceProvider, HttpClientConfiguration}?)(IServiceCollection)"/>
+/// Before using this test component, you need to register the necessary services by calling the AddHttpClients()
 /// method.
 /// </remarks>
 internal sealed class HttpClientRequestSender(string name) : TestComponent(name, type: TestStepType.ActionStep)
@@ -28,7 +27,7 @@ internal sealed class HttpClientRequestSender(string name) : TestComponent(name,
     /// </summary>
     /// <param name="url">A Uri object that represents the URL of the page being validated.</param>
     /// <param name="settings">A <see cref="TestSettings"/> object that contains the settings for the test.</param>
-    /// <param name="context">A <see cref="TestContext"/> object that represents the test session.</param>
+    /// <param name="context">A <see cref="TestContext"/> object that represents the test context.</param>
     /// <param name="serviceProvider">An instance object of a mechanism for retrieving a service object.</param>
     /// <param name="cancellationToken">An optional CancellationToken object that can be used to cancel the 
     /// this operation.</param>

src/XPing365.Sdk.Availability/TestValidators/BaseContentValidator.cs

@@ -5,8 +5,25 @@
 
 namespace XPing365.Sdk.Availability.TestValidators;
 
+/// <summary>
+/// Represents an abstract base class for validating HTTP content.
+/// </summary>
+/// <remarks>
+/// The BaseContentValidator class inherits from the TestComponent class and provides a common method for decoding 
+/// HTTP content.
+/// </remarks>
 public abstract class BaseContentValidator(string name) : TestComponent(name, TestStepType.ValidateStep)
 {
+    /// <summary>
+    /// Decodes the HTTP content from a byte array and content headers.
+    /// </summary>
+    /// <param name="data">The byte array that contains the HTTP content.</param>
+    /// <param name="contentHeaders">
+    /// The content headers that specify the encoding and media type of the content.
+    /// </param>
+    /// <returns>A string representation of the HTTP content.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when the data or contentHeaders parameter is null.</exception>
+    /// <exception cref="DecoderFallbackException">Thrown when a decoder fallback operation fails.</exception>
     protected static string GetContent(byte[] data, HttpContentHeaders contentHeaders)
     {
         ArgumentNullException.ThrowIfNull(data, nameof(data));

src/XPing365.Sdk.Availability/TestValidators/HttpResponseContentValidator.cs

@@ -65,6 +65,12 @@ public class HttpResponseContentValidator(
     Func<byte[], HttpContentHeaders, string>? onError = null) :
         TestComponent(StepName, TestStepType.ValidateStep)
 {
+    /// <summary>
+    /// The name of the test component that represents a HttpResponseContentValidator test operation.
+    /// </summary>
+    /// <remarks>
+    /// This constant is used to register the HttpResponseContentValidator class in the test framework.
+    /// </remarks>
     public const string StepName = "Server content response validation";
 
     private readonly Func<byte[], HttpContentHeaders, bool> _isValid = isValid;

src/XPing365.Sdk.Availability/TestValidators/HttpResponseHeadersValidator.cs

@@ -34,6 +34,12 @@ public class HttpResponseHeadersValidator(
     Func<HttpResponseHeaders, bool> isValid,
     Func<HttpResponseHeaders, string>? onError = null) : TestComponent(StepName, TestStepType.ValidateStep)
 {
+    /// <summary>
+    /// The name of the test component that represents a HttpResponseHeadersValidator test operation.
+    /// </summary>
+    /// <remarks>
+    /// This constant is used to register the HttpResponseHeadersValidator class in the test framework.
+    /// </remarks>
     public const string StepName = "Http response headers validation";
 
     private readonly Func<HttpResponseHeaders, bool> _isValid = isValid;

src/XPing365.Sdk.Availability/TestValidators/HttpStatusCodeValidator.cs

@@ -32,6 +32,12 @@ public sealed class HttpStatusCodeValidator(
     Func<HttpStatusCode, bool> isValid,
     Func<HttpStatusCode, string>? onError = null) : TestComponent(StepName, TestStepType.ValidateStep)
 {
+    /// <summary>
+    /// The name of the test component that represents a HttpStatusCodeValidator test operation.
+    /// </summary>
+    /// <remarks>
+    /// This constant is used to register the HttpStatusCodeValidator class in the test framework.
+    /// </remarks>
     public const string StepName = "Http status code validation";
 
     private readonly Func<HttpStatusCode, bool> _isValid = isValid;

src/XPing365.Sdk.Availability/TestValidators/RegexContentValidator.cs

@@ -16,6 +16,12 @@ namespace XPing365.Sdk.Availability.TestValidators;
 /// </summary>
 public class RegexContentValidator : BaseContentValidator
 {
+    /// <summary>
+    /// The name of the test component that represents a RegexContentValidator test operation.
+    /// </summary>
+    /// <remarks>
+    /// This constant is used to register the RegexContentValidator class in the test framework.
+    /// </remarks>
     public const string StepName = "Regex content validator";
 
     private readonly Func<Regex> GetRegex;

src/XPing365.Sdk.Availability/TestValidators/StringContentValidator.cs

@@ -15,6 +15,12 @@ namespace XPing365.Sdk.Availability.TestValidators;
 /// </summary>
 public class StringContentValidator : BaseContentValidator
 {
+    /// <summary>
+    /// The name of the test component that represents a StringContentValidator test operation.
+    /// </summary>
+    /// <remarks>
+    /// This constant is used to register the StringContentValidator class in the test framework.
+    /// </remarks>
     public const string StepName = "String content validator";
 
     private readonly Func<string, bool> _isValid;

src/XPing365.Sdk.Availability/TestValidators/XPathContentValidator.cs

@@ -17,6 +17,12 @@ namespace XPing365.Sdk.Availability.TestValidators;
 /// </summary>
 public class XPathContentValidator : BaseContentValidator
 {
+    /// <summary>
+    /// The name of the test component that represents a XPathContentValidator test operation.
+    /// </summary>
+    /// <remarks>
+    /// This constant is used to register the XPathContentValidator class in the test framework.
+    /// </remarks>
     public const string StepName = "Regex content validator";
 
     private readonly XPathExpression _xpath;

src/XPing365.Sdk.Availability/XPing365.Sdk.Availability.csproj

@@ -2,6 +2,7 @@
 
   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <NuspecFile>..\..\nuspec\XPing365.Availability.nuspec</NuspecFile>
   </PropertyGroup>
 

src/XPing365.Sdk.Core/Common/Error.cs

@@ -29,6 +29,11 @@ public sealed class Error(string code, string message) : IEquatable<Error>
     /// </summary>
     public string Message { get; } = message.RequireNotNullOrEmpty(nameof(message));
 
+    /// <summary>
+    /// Determines whether the current Error object is equal to another Error object.
+    /// </summary>
+    /// <param name="other">The Error object to compare with the current object.</param>
+    /// <returns>true if the current object and other have the same value; otherwise, false.</returns>
     public bool Equals(Error? other)
     {
         if (other is null)
@@ -49,16 +54,33 @@ public bool Equals(Error? other)
         return Code == other.Code;
     }
 
+    /// <summary>
+    /// Determines whether the current Error object is equal to a specified object.
+    /// </summary>
+    /// <param name="obj">The object to compare with the current object.</param>
+    /// <returns>
+    /// true if the current object and obj are both Error objects and have the same value; otherwise, false.
+    /// </returns>
     public override bool Equals(object? obj)
     {
         return Equals(obj as Error);
     }
 
+    /// <summary>
+    /// Returns the hash code for the current Error object.
+    /// </summary>
+    /// <returns>A 32-bit signed integer hash code.</returns>
     public override int GetHashCode()
     {
         return string.GetHashCode(Code, StringComparison.InvariantCulture);
     }
 
+    /// <summary>
+    /// Determines whether two Error objects have the same value.
+    /// </summary>
+    /// <param name="lhs">The first Error object to compare.</param>
+    /// <param name="rhs">The second Error object to compare.</param>
+    /// <returns>true if lhs and rhs have the same value; otherwise, false.</returns>
     public static bool operator ==(Error? lhs, Error? rhs)
     {
         if (lhs is null || rhs is null)
@@ -69,6 +91,12 @@ public override int GetHashCode()
         return lhs.Equals(rhs);
     }
 
+    /// <summary>
+    /// Determines whether two Error objects have different values.
+    /// </summary>
+    /// <param name="lhs">The first Error object to compare.</param>
+    /// <param name="rhs">The second Error object to compare.</param>
+    /// <returns>true if lhs and rhs have different values; otherwise, false.</returns>
     public static bool operator !=(Error? lhs, Error? rhs)
     {
         if (lhs is null || rhs is null)
@@ -79,8 +107,17 @@ public override int GetHashCode()
         return !lhs.Equals(rhs);
     }
 
+    /// <summary>
+    /// Converts an Error object to a string representation.
+    /// </summary>
+    /// <param name="error">The Error object to convert.</param>
+    /// <returns>A string that represents the error.</returns>
     public static implicit operator string(Error error) => error.RequireNotNull(nameof(error)).ToString();
 
+    /// <summary>
+    /// Returns a string that represents the current Error object.
+    /// </summary>
+    /// <returns>A string that represents the current object.</returns>
     public override string ToString()
     {
         return $"Error {Code}: {Message}";

src/XPing365.Sdk.Core/Common/InstrumentationLog.cs

@@ -24,6 +24,11 @@ public sealed class InstrumentationLog : IDisposable
     private readonly Action<InstrumentationLog>? _callback;
     private DateTime _startTime = DateTime.Today;
 
+    /// <summary>
+    /// Initializes a new instance of the InstrumentationLog class.
+    /// </summary>
+    /// <param name="callback">An optional callback action that will be invoked when the instance is disposed.</param>
+    /// <param name="startStopwatch">A flag indicating whether to start the stopwatch automatically.</param>
     public InstrumentationLog(Action<InstrumentationLog>? callback = null, bool startStopwatch = true)
     {
         _callback = callback;
@@ -70,6 +75,12 @@ public void Restart()
         _stopwatch.Restart();
     }
 
+    /// <summary>
+    /// Releases the resources used by the InstrumentationLog instance.
+    /// </summary>
+    /// <remarks>
+    /// This method stops the stopwatch and invokes the callback action if provided.
+    /// </remarks>
     public void Dispose()
     {
         Dispose(true);

src/XPing365.Sdk.Core/Common/PropertyBag.cs

@@ -25,17 +25,31 @@ public sealed class PropertyBag<TValue> : ISerializable
     /// </summary>
     public ReadOnlyCollection<PropertyBagKey> Keys => _properties.Keys.ToList().AsReadOnly();
 
+    /// <summary>
+    /// Initializes a new instance of the PropertyBag class.
+    /// </summary>
+    /// <param name="properties">An optional dictionary of properties to initialize the property bag with.</param>
     public PropertyBag(IDictionary<PropertyBagKey, TValue>? properties = null)
     {
         _properties = properties?.ToDictionary() ?? [];
-    } 
+    }
 
-    // Constructor for deserialization
+    /// <summary>
+    /// Initializes a new instance of the PropertyBag class with serialized data.
+    /// </summary>
+    /// <param name="info">The SerializationInfo that holds the serialized object data.</param>
+    /// <param name="context">
+    /// The StreamingContext that contains contextual information about the source or destination.
+    /// </param>
+    /// <remarks>
+    /// The PropertyBag class implements the ISerializable interface and can be serialized and deserialized using binary 
+    /// or XML formatters.
+    /// </remarks>
     public PropertyBag(SerializationInfo info, StreamingContext context)
     {
         ArgumentNullException.ThrowIfNull(info, nameof(info));
 
-        if (info.GetValue(SerializableEntryName, typeof(Dictionary<PropertyBagKey, TValue>)) 
+        if (info.GetValue(SerializableEntryName, typeof(Dictionary<PropertyBagKey, TValue>))
             is Dictionary<PropertyBagKey, TValue> properties)
         {
             _properties = properties;

src/XPing365.Sdk.Core/Common/PropertyBagKey.cs

@@ -17,16 +17,32 @@ public class PropertyBagKey(string key) : IEquatable<PropertyBagKey?>
 {
     private readonly string _key = key.RequireNotNullOrEmpty(nameof(key));
 
+    /// <summary>
+    /// Determines whether the current PropertyBagKey object is equal to a specified object.
+    /// </summary>
+    /// <param name="obj">The object to compare with the current object.</param>
+    /// <returns>
+    /// true if the current object and obj are both PropertyBagKey objects and have the same value; otherwise, false.
+    /// </returns>
     public override bool Equals(object? obj)
     {
         return Equals(obj as PropertyBagKey);
     }
 
+    /// <summary>
+    /// Determines whether the current PropertyBagKey object is equal to another PropertyBagKey object.
+    /// </summary>
+    /// <param name="other">The PropertyBagKey object to compare with the current object.</param>
+    /// <returns>true if the current object and other have the same value; otherwise, false.</returns>
     public bool Equals(PropertyBagKey? other)
     {
         return other is not null && _key == other._key;
     }
 
+    /// <summary>
+    /// Returns the hash code for the current PropertyBagKey object.
+    /// </summary>
+    /// <returns>A 32-bit signed integer hash code.</returns>
     public override int GetHashCode()
     {
         return HashCode.Combine(_key);
@@ -56,6 +72,10 @@ public override int GetHashCode()
         return !(left == right);
     }
 
+    /// <summary>
+    /// Returns a string that represents the current Error object.
+    /// </summary>
+    /// <returns>A string that represents the current object.</returns>
     public override string ToString() => _key;
 
     private string GetDebuggerDisplay() => _key;