From 5f488afb56afb3fc2e26971ea3d5b02959d606d6 Mon Sep 17 00:00:00 2001
From: Elizabeth Mattijsen <liz@raku.rocks>
Date: Tue, 4 Jul 2023 15:42:42 +0200
Subject: [PATCH] RakuAST: add Doc::Declarator.paragraphs method

This basically adds support for Markup to declarator docs.

The reasons for adding a separate .paragraphs method are:
- wanting to be able to have markup extend over a multiple lines
- making leading / trailing to be markup aware is a bit troublesome
  because they can each be added per-line (and trailing declarator
  docs are added that way in the Raku grammar).  This meant that
  either any addition would need to re-stringify what it got already,
  add the new line, and then look for markup again.  Yuck.

The alternative would be to run the check for markup at CHECK time.
However, it turns out that the CHECK time logic can actually be called
multiple times when a separate .AST step is taken (once for the .AST,
and once for the subsequent .EVAL on it).

So it felt better to keep the current leading / trailing semantics
and create an opt-in method 'paragraphs' that returns a 2-element
list with the leading (first element) and trailing (second element)
declarator doc parsed through the markup logic.  And since this is
completely opt-in, if not used, will not cause any extra CPU to be
used.

The elements are either a string (if no markup was found) or a
RakuAST::Doc::Paragraph object.

Producing the AST for all declarator docs from a given AST is:
    $ast.map: {
        .WHY andthen .paragraphs if $_ ~~ RakuAST::Doc::DeclaratorTarget
    }
---
 src/Raku/ast/doc-declarator.rakumod  |  1 +
 src/core.c/RakuAST/Fixups.pm6        | 17 +++++++++++++
 t/12-rakuast/doc-declarator.rakutest | 37 +++++++++++++++++++++++++---
 3 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/src/Raku/ast/doc-declarator.rakumod b/src/Raku/ast/doc-declarator.rakumod
index 2aff0d71782..9b0148abc8f 100644
--- a/src/Raku/ast/doc-declarator.rakumod
+++ b/src/Raku/ast/doc-declarator.rakumod
@@ -7,6 +7,7 @@ class RakuAST::Doc::Declarator
     has List                           $.leading;
     has List                           $.trailing;
     has int                            $!pod-index;
+    has List                           $!paragraphs;
 
     method new(:$WHEREFORE, :$leading, :$trailing) {
         my $obj := nqp::create(self);
diff --git a/src/core.c/RakuAST/Fixups.pm6 b/src/core.c/RakuAST/Fixups.pm6
index d677c11a81c..a24aef3c7a8 100644
--- a/src/core.c/RakuAST/Fixups.pm6
+++ b/src/core.c/RakuAST/Fixups.pm6
@@ -1260,4 +1260,21 @@ augment class RakuAST::Type::Enum {
     }
 }
 
+augment class RakuAST::Doc::Declarator {
+
+    # Return a 2-element list with all of the leading doc joined and
+    # parsed as the first elements, and the trailing doc joined and
+    # parsed as the second element
+    method paragraphs() {
+        $!paragraphs
+          // nqp::bindattr(self,RakuAST::Doc::Declarator,'$!paragraphs',
+               (self.leading, self.trailing).map({
+                 $_
+                   ?? RakuAST::Doc::Paragraph.from-string(.join("\n"))
+                   !! ''
+               }).List
+             )
+    }
+}
+
 # vim: expandtab shiftwidth=4
diff --git a/t/12-rakuast/doc-declarator.rakutest b/t/12-rakuast/doc-declarator.rakutest
index 002dda120c8..e979bf3ff74 100644
--- a/t/12-rakuast/doc-declarator.rakutest
+++ b/t/12-rakuast/doc-declarator.rakutest
@@ -823,18 +823,47 @@ subtest 'a simple lexical var' => {
       sigil       => '$',
       desigilname => RakuAST::Name.from-identifier('foo'),
     ).declarator-docs(
-      leading  => ("leading comment\n",),
-      trailing => ("trailing comment\n",)
+      leading  => ("leading B<comment>\n",),
+      trailing => ("trailing C<comment>\n",)
     );
 
     is-deeply $deparsed, q:to/CODE/.chomp, 'deparse';
-#| leading comment
-my $foo #= trailing comment
+#| leading B<comment>
+my $foo #= trailing C<comment>
 , $=pod
 CODE
 
     # since the $=pod semantics are unsure, we're not going
     # to test that here and now
+
+    is-deeply
+      $ast.first(RakuAST::Doc::DeclaratorTarget).WHY.paragraphs,
+      (RakuAST::Doc::Paragraph.new(
+        "leading ",
+        RakuAST::Doc::Markup.new(
+          letter => "B",
+          opener => "<",
+          closer => ">",
+          atoms  => (
+            "comment",
+          )
+        ),
+        "\n"
+      ),
+      RakuAST::Doc::Paragraph.new(
+        "trailing ",
+        RakuAST::Doc::Markup.new(
+          letter => "C",
+          opener => "<",
+          closer => ">",
+          atoms  => (
+            "comment",
+          )
+        ),
+        "\n"
+      )
+    ),
+    'did we find the paragraphs ok';
 }
 
 # vim: expandtab shiftwidth=4