From b946c811c33480ba48be2dd84b5f2867bb00167f Mon Sep 17 00:00:00 2001
From: Gabriele Santomaggio <G.santomaggio@gmail.com>
Date: Tue, 23 Jan 2024 10:21:48 +0100
Subject: [PATCH] documentation [skip ci]

Signed-off-by: Gabriele Santomaggio <G.santomaggio@gmail.com>
---
 RabbitMQ.Stream.Client/AbstractEntity.cs      |  6 ++++
 .../PublicAPI.Unshipped.txt                   |  1 -
 .../Reliable/ReliableBase.cs                  | 29 +++++++++++++++----
 3 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/RabbitMQ.Stream.Client/AbstractEntity.cs b/RabbitMQ.Stream.Client/AbstractEntity.cs
index 9476d105..0c2b7aed 100644
--- a/RabbitMQ.Stream.Client/AbstractEntity.cs
+++ b/RabbitMQ.Stream.Client/AbstractEntity.cs
@@ -14,6 +14,12 @@ public abstract record EntityCommonConfig
         internal ConnectionsPool Pool { get; set; }
         public Func<MetaDataUpdate, Task> MetadataHandler { get; set; }
 
+        /// <summary>
+        /// The Identifier does not have any effect on the server.
+        /// It is used to identify the entity in the logs and on the UI (only for the consumer)
+        /// It is possible to retrieve the entity info using the Info.Identifier method form the
+        /// raw* instances.
+        /// </summary>
         public string Identifier { get; set; }
     }
 
diff --git a/RabbitMQ.Stream.Client/PublicAPI.Unshipped.txt b/RabbitMQ.Stream.Client/PublicAPI.Unshipped.txt
index af20df85..7e65f49a 100644
--- a/RabbitMQ.Stream.Client/PublicAPI.Unshipped.txt
+++ b/RabbitMQ.Stream.Client/PublicAPI.Unshipped.txt
@@ -209,7 +209,6 @@ RabbitMQ.Stream.Client.Reliable.ProducerConfig.Filter.set -> void
 RabbitMQ.Stream.Client.Reliable.ProducerConfig.Reference.set -> void
 RabbitMQ.Stream.Client.Reliable.ProducerFactory.CreateProducer(bool boot) -> System.Threading.Tasks.Task<RabbitMQ.Stream.Client.IProducer>
 RabbitMQ.Stream.Client.Reliable.ProducerFactory._producer -> RabbitMQ.Stream.Client.IProducer
-RabbitMQ.Stream.Client.Reliable.ReliableBase.CompareStatus(RabbitMQ.Stream.Client.Reliable.ReliableEntityStatus toTest) -> bool
 RabbitMQ.Stream.Client.Reliable.ReliableBase.UpdateStatus(RabbitMQ.Stream.Client.Reliable.ReliableEntityStatus status) -> void
 RabbitMQ.Stream.Client.Reliable.ReliableBase._status -> RabbitMQ.Stream.Client.Reliable.ReliableEntityStatus
 RabbitMQ.Stream.Client.Reliable.ReliableConfig.Identifier.get -> string
diff --git a/RabbitMQ.Stream.Client/Reliable/ReliableBase.cs b/RabbitMQ.Stream.Client/Reliable/ReliableBase.cs
index 3dbd9683..23f0be74 100644
--- a/RabbitMQ.Stream.Client/Reliable/ReliableBase.cs
+++ b/RabbitMQ.Stream.Client/Reliable/ReliableBase.cs
@@ -11,9 +11,25 @@ namespace RabbitMQ.Stream.Client.Reliable;
 
 public record ReliableConfig
 {
+    /// <summary>
+    /// The interface to reconnect the entity to the server.
+    /// By default it uses a BackOff pattern. See <see cref="BackOffReconnectStrategy"/>
+    /// </summary>
     public IReconnectStrategy ReconnectStrategy { get; set; }
+
+    /// <summary>
+    /// The interface to check if the resource is available.
+    /// A stream could be not fully ready during the restarting.
+    /// By default it uses a BackOff pattern. See <see cref="ResourceAvailableBackOffReconnectStrategy"/>
+    /// </summary>
     public IReconnectStrategy ResourceAvailableReconnectStrategy { get; set; }
 
+    /// <summary>
+    /// The Identifier does not have any effect on the server.
+    /// It is used to identify the entity in the logs and on the UI (only for the consumer)
+    /// It is possible to retrieve the entity info using the Info.Identifier method form the
+    /// Producer/Consumer instances.
+    /// </summary>
     public string Identifier { get; set; }
 
     public StreamSystem StreamSystem { get; }
@@ -33,12 +49,15 @@ protected ReliableConfig(StreamSystem streamSystem, string stream)
     }
 }
 
+/// <summary>
+/// The ReliableEntityStatus is used to check the status of the ReliableEntity.
+/// </summary>
 public enum ReliableEntityStatus
 {
-    Initialization,
-    Open,
-    Reconnecting,
-    Closed,
+    Initialization,// the entity is initializing
+    Open, // the entity is open and ready to use
+    Reconnecting,// the entity is reconnecting but still can be used
+    Closed,// the entity is closed and cannot be used anymore
 }
 
 /// <summary>
@@ -64,7 +83,7 @@ protected void UpdateStatus(ReliableEntityStatus status)
         }
     }
 
-    protected bool CompareStatus(ReliableEntityStatus toTest)
+    private bool CompareStatus(ReliableEntityStatus toTest)
     {
         lock (_lock)
         {