package RakuAST::Doc { }

The RakuAST::Doc package serves as a common namespace for all classes that provide RakuDoc functionality.

Support for RakuAST functionality is available in language version 6.e+ and was added in Rakudo compiler release 2023.02. In earlier language versions it is only available when specifying:

use experimental :rakuast;

Classes

Relations between the RakuAST::Doc:: classes:

    RakuAST::Doc::Block
     \- paragraphs
         |- string
         |- RakuAST::Doc::Paragraph
         |   \- atoms
         |       |- string
         |       \- RakuAST::Doc::Markup
         |           \- atoms
         |               |- string
         |               \- RakuAST::Doc::Markup
         \- RakuAST::Doc::Block

Note that this structure is recursive with regards to the RakuAST::Doc::Block object (which can occur as an element of the paragraphs of a RakuAST::Doc::Block), and the RakuAST::Doc::Markup object (which can occur as an element of the atoms of a RakuAST::Doc::Markup).

class RakuAST::Doc::Block

The RakuAST::Doc::Block object contains the information about a block of RakuDoc. It has a type ("foo" in the case of =begin foo) and it has zero or more paragraphs. Each paragraph may consist of a string (which implies there is no extra markup in there) or a RakuAST::Doc::Paragraph object, or another RakuAST::Doc::Block in the case of RakuDoc blocks embedding other blocks.

A RakuAST::Doc::Block typically occurs in RakuAST::StatementList objects when it is the result of parsing Raku Programming Language code, or RakuDoc documentation.

class RakuAST::Doc::Paragraph

The RakuAST::Doc::Paragraph object contains the information about the atoms that constitute the paragraph. Each atom may be either a string or a RakuAST::Doc::Markup object.

class RakuAST::Doc::Markup

The RakuAST::Doc::Markup object contains the information about a markup atom, and itself contains a list of atoms. Each atom may be either a string or a RakuAST::Doc::Markup object in the case of embedded markup.

EXAMPLE

This small piece of RakuDoc:

=begin rakudoc
This is L<B<example>|https://example.com>>.
=end rakudoc

is represented in RakuAST::Doc:: objects like this:

RakuAST::Doc::Block.new(
  type       => "rakudoc",
  paragraphs => (
    RakuAST::Doc::Paragraph.new(
      "This is ",
      RakuAST::Doc::Markup.new(
        letter => "L",
        opener => "<",
        closer => ">",
        atoms  => (
          RakuAST::Doc::Markup.new(
            letter => "B",
            opener => "<",
            closer => ">",
            atoms  => (
              "example",
            )
          ),
        ),
        meta   => (
          "https://example.com",
        )
      ),
      ">.\n"
    ),
  )
);

class RakuAST::Doc::Declarator

The RakuAST::Doc::Declarator object contains the leading and trailing documentation of a RakuAST object doing the RakuAST::Doc::DeclaratorTarget role.

role RakuAST::Doc::DeclaratorTarget

The RakuAST::Doc::DeclaratorTarget role is done by RakuAST objects that allow leading and/or trailing documentation when used in Raku source code.

EXAMPLE

Raku code with leading and trailing declarator doc:

#| important variable
my $foo;  #= really!

is represented like this:

RakuAST::VarDeclaration::Simple.new(
  sigil       => "\$",
  desigilname => RakuAST::Name.from-identifier("foo")
).declarator-docs(
  leading  => (
    "important variable\n",
  ),
  trailing => (
    "really!\n",
  )
);

Note that the representation is not showing the actual RakuAST::Doc::Declarator object. This is hidden in the .declarator-docs call.

This is needed to create a single-statement representation of the target object (in this case the RakuAST::VarDeclaration::Simple object) and its associated RakuAST::Doc::Declarator object.

That is because objects doing the RakuAST::Doc::DeclaratorTarget refer to the associated RakuAST::Doc::Declarator object in the .WHY method. But conversely, the RakuAST::Doc::Declarator object refers to its subject with the .WHEREFORE method. So there's a chicken-and-egg problem, which was solved by introducing the .declarator-docs method on objects doing the RakuAST::Doc::DeclaratorTarget role.