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

@@ -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);

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

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