declarator blocks

Documentation for declarator blocks assembled from the following types:

language documentation Perl 6 pod

From Perl 6 pod

(Perl 6 pod) declarator blocks

Declarator blocks differ from the others by not having a specific type, instead they are attached to some source code.

Declarator blocks are introduced by a special comment: either #| or #=, which must be immediately followed by either a space or an opening bracket. If followed by a space, the block is terminated by the end of line; if followed by one or more opening brackets, the block is terminated by the matching sequence of closing brackets.

Blocks starting with #| are attached to the code after them, and blocks starting with #= are attached to the code before them.

Since declarator blocks are attached to source code, they can be used to document classes, roles, subroutines etc.

The WHY method can be used on these classes, roles, subroutines etc. to return the attached Pod value.

#| Base class for magicians 
class Magician {
  has Int $.level;
  has Str @.spells;
}
 
#| Fight mechanics 
sub duel(Magician $aMagician $b{
}
#= Magicians only, no mortals. 
 
say Magician.WHY# OUTPUT: «Base class for magicians␤» 
say &duel.WHY.leading# OUTPUT: «Fight mechanics␤» 
say &duel.WHY.trailing# OUTPUT: «Magicians only, no mortals.␤» 

These declarations can extend multiple blocks:

#|( This is an example of stringification: 
    * Numbers turn into strings
    * Regexes operate on said strings
    * C<with> topicalizes and places result into $_
)
sub search-in-seqInt $endInt $number ) {
    with (^$end).grep( /^$number/ ) {
        .say for $_<>;
    }
}
#=« Uses 
    * topic
    * decont operator
»

By using a matched pair of parenthesis constructs such as () or «» the comments can extend multiple lines. This format, however, will not translate to a multi-line display by perl6 -doc.