From b8956e47305541337315165194cadd109d5daf4c Mon Sep 17 00:00:00 2001
From: Matthias Beerens <3512339+Matthiee@users.noreply.github.com>
Date: Mon, 7 Oct 2024 11:03:12 +0200
Subject: [PATCH] Improve the examples with code comments.

---
 README.md | 36 ++++++++++++++++++++++++++----------
 1 file changed, 26 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 12ee8a0..2e6df50 100644
--- a/README.md
+++ b/README.md
@@ -13,8 +13,10 @@ This package provides a simple yet configurable solution.
 ## Features
 
 - [x] Request/Response
-- [x] Pipelines
+- [x] Commands
+- [x] Request/Command Pipelines
 - [x] Events
+- [x] Event Observers
 
 ## Sending events
 
@@ -23,16 +25,21 @@ An event can have multiple handlers. All handlers will be executed in parallel (
 ```dart
 import 'package:dart_mediator/mediator.dart';
 
+/// Strongly typed event class containing the event data.
+/// All events must implement the [DomainEvent] interface.
 class MyEvent implements DomainEvent {}
 
 Future<void> main() async {
   final mediator = Mediator.create();
 
+  // Subscribe to the event.
   mediator.events.on<MyEvent>()
     .subscribeFunction(
       (event) => print('event received'),
     );
 
+  // Sends the event to all handlers.
+  // This will print 'event received'.
   await mediator.events.dispatch(MyEvent());
 }
 ```
@@ -42,6 +49,7 @@ Future<void> main() async {
 A command can only have one handler and doesn't return a value.
 
 ```dart
+/// This command will not return a value.
 class MyCommand implements Command {}
 
 class MyCommandHandler implements CommandHandler<MyCommand> {
@@ -56,6 +64,7 @@ Future<void> main() async {
 
   mediator.requests.register(MyCommandHandler());
 
+  /// Sends the command request. Return value is [void].
   await mediator.requests.send(MyCommand());
 }
 ```
@@ -69,6 +78,7 @@ import 'package:dart_mediator/mediator.dart';
 
 class Something {}
 
+/// This query will return a [Something] object.
 class MyQuery implements Query<Something> {}
 
 class MyQueryHandler implements QueryHandler<Something, MyQuery> {
@@ -84,28 +94,33 @@ Future<void> main() async {
 
   mediator.requests.register(MyQueryHandler());
 
+  // Sends the query request and returns the response.
   final Something response = await mediator.requests.send(MyQuery());
 
   print(response);
 }
 ```
 
-## Add event logging
+## Event Observers
 
-An observer can be used to log events being dispatched and handled.
+An observer can be used to observe events being dispatched, handled or when an error occurs. For example logging events.
 
 ```dart
 class LoggingEventObserver implements EventObserver {
+
+  /// Called when an event is dispatched but before any handlers have
+  /// been called.
   @override
   void onDispatch<TEvent extends DomainEvent>(
     TEvent event,
     Set<EventHandler<TEvent>> handlers,
   ) {
     print(
-      '[$LoggingEventObserver] onDispatch "$event" with ${handlers.length} handlers',
+      '[LoggingEventObserver] onDispatch "$event" with ${handlers.length} handlers',
     );
   }
 
+  /// Called when an event returned an error for a given handler.
   @override
   void onError<TEvent extends DomainEvent>(
     TEvent event,
@@ -113,34 +128,35 @@ class LoggingEventObserver implements EventObserver {
     Object error,
     StackTrace stackTrace,
   ) {
-    print('[$LoggingEventObserver] onError $event -> $handler ($error)');
+    print('[LoggingEventObserver] onError $event -> $handler ($error)');
   }
 
+  /// Called when an event has been handled by a handler.
   @override
   void onHandled<TEvent extends DomainEvent>(
     TEvent event,
     EventHandler<TEvent> handler,
   ) {
-    print('[$LoggingEventObserver] onHandled $event -> $handler');
+    print('[LoggingEventObserver] onHandled $event -> $handler');
   }
 }
 
 void main() {
   final mediator = Mediator.create(
+    // Adds the logging event observer.
     observers: [LoggingEventObserver()],
   );
 
-  // do something
+  // Dispatch an event.
 }
 
 ```
 
-## Request pipeline behavior
+## Request/Command Pipeline Behavior
 
-A pipeline behavior can be used to add cross cutting concerns to requests. For example logging.
+A pipeline behavior can be used to add cross cutting concerns to requests/commands. For example logging.
 
 ```dart
-
 class LoggingBehavior implements PipelineBehavior {
   @override
   Future handle(request, RequestHandlerDelegate next) async {