From 7b20a491b424cf406f15ff95d20aa997c667a7ae Mon Sep 17 00:00:00 2001
From: Bartek Kryza <bkryza@gmail.com>
Date: Thu, 22 Sep 2022 19:33:08 +0200
Subject: [PATCH] Added paragaph array to clang comment parser

---
 docs/configuration_file.md                  | 21 +++++++++++++++++++++
 src/common/visitor/comment/clang_visitor.cc |  5 +++++
 tests/t00050/.clang-uml                     | 12 ++++++++++++
 tests/t00050/t00050.cc                      | 10 +++++++++-
 tests/t00050/test_case.h                    |  3 +++
 5 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/docs/configuration_file.md b/docs/configuration_file.md
index ce309c8a..f16714b0 100644
--- a/docs/configuration_file.md
+++ b/docs/configuration_file.md
@@ -121,6 +121,27 @@ generate notes in the PlantUML diagram from code comments (see also test case [t
           {% endif %}
           {% endfor %}
 ```
+Currently there are 2 available comment parsers:
+* `plain` - default
+* `clang`
+They can be selected using `comment_parser` config option.
+
+#### `plain` comment parser
+This parser provides only 2 options to the Jinja context:
+* `comment.raw` - raw comment text, including comment markers such as `///` or `/**`
+* `comment.formatted` - formatted entire comment
+
+#### `clang` comment parser
+This parser uses Clang comment parsing API to extract commands from the command:
+* `comment.raw` - raw comment text, including comment markers such as `///` or `/**`
+* `comment.formatted` - formatted entire comment
+* `comment.<command>.<N>` - where command is the command used in the command e.g. `brief`, `todo`, etc. 
+   and `N` is the index of the command in the array (each comment can have multiple instances of the 
+   same command such as `\todo`)
+* `comment.text` - entire text of the comment that is not attached to any command
+* `comment.paragraph.<N>` - array of plain text paragraphs, for instance if you don't use `\brief`
+  commands but often provide brief description as first sentence of the comment separated with a new line
+  from the rest of the comment
 
 ## Example complete config
 
diff --git a/src/common/visitor/comment/clang_visitor.cc b/src/common/visitor/comment/clang_visitor.cc
index 07cdf5a8..e3d24c1b 100644
--- a/src/common/visitor/comment/clang_visitor.cc
+++ b/src/common/visitor/comment/clang_visitor.cc
@@ -69,6 +69,11 @@ void clang_visitor::visit(
 
             cmt["text"] =
                 cmt["text"].get<std::string>() + "\n" + paragraph_text;
+
+            if (!cmt.contains("paragraph"))
+                cmt["paragraph"] = inja::json::array();
+
+            cmt["paragraph"].push_back(paragraph_text);
         }
         else if (block_kind == Comment::TextCommentKind) {
             // TODO
diff --git a/tests/t00050/.clang-uml b/tests/t00050/.clang-uml
index 724a323d..eb7a1326 100644
--- a/tests/t00050/.clang-uml
+++ b/tests/t00050/.clang-uml
@@ -24,7 +24,19 @@ diagrams:
           note left of {{ alias("C") }} #AABBCC                 
              {{ trim(comment("clanguml::t00050::C").text) }}          
           end note
+        - >
+          {% set cmt=comment("clanguml::t00050::G").paragraph %}
+          note top of {{ alias("G") }}
+             {{ trim(cmt.0) }}
+          end note
 
+          note right of {{ alias("G") }}
+             {{ trim(cmt.1) }}
+          end note
+
+          note bottom of {{ alias("G") }}
+             {{ trim(cmt.2) }}
+          end note
         - >
           {# Render brief comments and todos, if any were written for an element #}
           {% for e in diagram.elements %}
diff --git a/tests/t00050/t00050.cc b/tests/t00050/t00050.cc
index 978d95ce..fe2953b5 100644
--- a/tests/t00050/t00050.cc
+++ b/tests/t00050/t00050.cc
@@ -69,7 +69,7 @@ namespace utils {
 class D {
 };
 
-}
+} // namespace utils
 
 /// Mollis pretium lorem primis
 enum class E { E1, E2, E3 };
@@ -88,6 +88,14 @@ template <typename T, typename V, int N> class F {
     V v;
 };
 
+/// This is a short description of class G.
+///
+/// This is an intermediate description of class G.
+///
+/// This is a long description of class G.
+class G {
+};
+
 class NoComment {
 };
 
diff --git a/tests/t00050/test_case.h b/tests/t00050/test_case.h
index e11d0d36..675a1ac1 100644
--- a/tests/t00050/test_case.h
+++ b/tests/t00050/test_case.h
@@ -49,6 +49,9 @@ TEST_CASE("t00050", "[test-case][class]")
     REQUIRE_THAT(puml, !HasNote(_A("E"), "bottom"));
     REQUIRE_THAT(puml, !HasNote(_A("NoComment"), "top"));
     REQUIRE_THAT(puml, HasNote(_A("F<T,V,int N>"), "top"));
+    REQUIRE_THAT(puml, HasNote(_A("G"), "top"));
+    REQUIRE_THAT(puml, HasNote(_A("G"), "bottom"));
+    REQUIRE_THAT(puml, HasNote(_A("G"), "right"));
 
     save_puml(
         "./" + config.output_directory() + "/" + diagram->name + ".puml", puml);