Document outcome (#69)

Signed-off-by: Gabriele Santomaggio <[email protected]>

Author: Gsantomaggio

RabbitMQ.AMQP.Client/IPublisher.cs

@@ -15,43 +15,54 @@ public PublisherException(string message) : base(message)
         }
     }
 
+    /// <summary>
+    ///  Represents the status of a publish operation.
+    ///  Accepted: The message was accepted for publication.
+    ///  Rejected: The message was rejected by the broker.
+    ///  Released: The message was released by the broker.
+    /// </summary>
     public enum OutcomeState
     {
         Accepted,
         Rejected,
         Released,
     }
+    
+    /// <summary>
+    ///  PublishOutcome represents the outcome of a publish operation.
+    ///  It contains the state of the outcome and an error if the outcome is not successful.
+    /// </summary>
 
     public class PublishOutcome
     {
-        private readonly OutcomeState _state;
-        private readonly Error? _error;
-
         public PublishOutcome(OutcomeState state, Error? error)
         {
-            _state = state;
-            _error = error;
+            State = state;
+            Error = error;
         }
 
-        public OutcomeState State => _state;
-        public Error? Error => _error;
+        public OutcomeState State { get; }
+
+        public Error? Error { get; }
     }
 
     public class PublishResult
     {
-        private IMessage _message;
-        private PublishOutcome _outcome;
-
         public PublishResult(IMessage message, PublishOutcome outcome)
         {
-            _message = message;
-            _outcome = outcome;
+            Message = message;
+            Outcome = outcome;
         }
 
-        public IMessage Message => _message;
-        public PublishOutcome Outcome => _outcome;
+        public IMessage Message { get; }
+
+        public PublishOutcome Outcome { get; }
     }
 
+    /// <summary>
+    ///  Interface for publishing messages to an AMQP broker.
+    ///  Implementations of this interface are expected to be thread-safe.
+    /// </summary>
     public interface IPublisher : ILifeCycle
     {
         Task<PublishResult> PublishAsync(IMessage message, CancellationToken cancellationToken = default);

RabbitMQ.AMQP.Client/Impl/AmqpPublisher.cs

@@ -99,18 +99,18 @@ await base.OpenAsync()
             }
         }
 
-        // TODO: Consider implementing this method with the send method
-        // a way to send a batch of messages
-
-        // protected override async Task<int> ExecuteAsync(SenderLink link)
-        // {
-        //     int batch = this.random.Next(1, this.role.Args.Batch);
-        //     Message[] messages = CreateMessages(this.id, this.total, batch);
-        //     await Task.WhenAll(messages.Select(m => link.SendAsync(m)));
-        //     this.total += batch;
-        //     return batch;
-        // }
-
+       
+        /// <summary>
+        /// Publishes a message to the broker in an asynchronous manner.
+        /// The PublishResult is synchronous. In order to increase the performance
+        /// you can use more tasks to publish messages in parallel
+        /// </summary>
+        /// <param name="message"></param>
+        /// <param name="cancellationToken"></param>
+        /// <returns></returns>
+        /// <exception cref="InvalidOperationException"></exception>
+        /// <exception cref="NotSupportedException"></exception>
+        /// <exception cref="PublisherException"></exception>
         public async Task<PublishResult> PublishAsync(IMessage message, CancellationToken cancellationToken = default)
         {
             ThrowIfClosed();

docs/Examples/GettingStarted/Program.cs

@@ -71,10 +71,14 @@
         case OutcomeState.Accepted:
             Trace.WriteLine(TraceLevel.Information, $"[Publisher] Message: {message.Body()} confirmed");
             break;
+        case OutcomeState.Released:
+            Trace.WriteLine(TraceLevel.Information, $"[Publisher] Message: {message.Body()} Released");
+            break;
+
+
         case OutcomeState.Rejected:
             Trace.WriteLine(TraceLevel.Error,
-                $"outcome result, state: {pr.Outcome.State}, message_id: " +
-                $"{message.MessageId()}, error: {pr.Outcome.Error}");
+                $"[Publisher] Message: {message.Body()} Rejected with error: {pr.Outcome.Error}");
             break;
         default:
             throw new ArgumentOutOfRangeException();