From 03ac2121bc587d26d4ffd3ddaf7fdf82ed230694 Mon Sep 17 00:00:00 2001
From: Bartek Kryza <bkryza@gmail.com>
Date: Sat, 21 Oct 2023 17:24:48 +0200
Subject: [PATCH] Updated docs

---
 README.md                 |  8 +++++++-
 docs/sequence_diagrams.md | 29 +++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 93d69455..acbf3b06 100644
--- a/README.md
+++ b/README.md
@@ -240,7 +240,10 @@ template <typename T> class Encoder : public T {
 public:
     bool send(std::string &&msg)
     {
-        return T::send(std::move(encode(std::move(msg))));
+        return T::send(std::move(
+            // Encode the message using Base64 encoding and pass it to the next
+            // layer
+            encode(std::move(msg))));
     }
 
 protected:
@@ -255,6 +258,7 @@ public:
 
         int retryCount = 5;
 
+        // Repeat until send() succeeds or retry count is exceeded
         while (retryCount--) {
             if (T::send(buffer))
                 return true;
@@ -284,8 +288,10 @@ int tmain()
 {
     auto pool = std::make_shared<Encoder<Retrier<ConnectionPool>>>();
 
+    // Establish connection to the remote server synchronously
     pool->connect();
 
+    // Repeat for each line in the input stream
     for (std::string line; std::getline(std::cin, line);) {
         if (!pool->send(std::move(line)))
             break;
diff --git a/docs/sequence_diagrams.md b/docs/sequence_diagrams.md
index 9f32dff9..86905283 100644
--- a/docs/sequence_diagrams.md
+++ b/docs/sequence_diagrams.md
@@ -9,6 +9,7 @@
 * [Customizing participants order](#customizing-participants-order)
 * [Generating return types](#generating-return-types)
 * [Generating condition statements](#generating-condition-statements)
+* [Including comments in sequence diagrams](#including-comments-in-sequence-diagrams)
 
 <!-- tocstop -->
 
@@ -315,3 +316,31 @@ generate_condition_statements: true
 An example of a diagram with this feature enabled is presented below:
 ![extension](test_cases/t20033_sequence.svg)
 
+## Including comments in sequence diagrams
+`clang-uml` can add code comments placed directly before are next to a call
+expression as notes in the diagram (see for instance
+[t20038](test_cases/t20038_sequence.svg)).
+
+This however is not enabled by default. In order to enable this feature it is
+necessary to first of all force Clang to parse all comments in the source
+code by adding the following compile flag at the top of `.clang-uml`:
+
+```yaml
+add_compile_flags:
+  - -fparse-all-comments
+```
+
+or adding it to the `compile_commands.json` database somehow directly.
+
+Another option needed to generate these comments in the diagram is to set
+
+```yaml
+   generate_message_comments: true
+```
+
+for each sequence diagram, which should include these comments.
+
+In case only selected messages should have some specific comments, instead
+of enabling the `generate_message_comments` option, it is possible to use
+`\uml{note TEXT}` directive in the comment above the expression, see
+[t20001](test_cases/t20001_sequence.svg).