Explain Declarator blocks in language/pod

Author: hankache

doc/Language/pod.pod6

@@ -22,7 +22,8 @@ A very simple Perl 6 Pod document
 =head1 Block Structure
 
 A Pod document may consist of multiple Pod blocks.
-There are three ways to define a block; all of which yield the same result.
+There are four ways to define a block (delimited, paragraph, abbreviated, declarator);
+the first three yield the same result but the fourth differs.
 You can use whichever form is most convenient for your particular documentation task.
 
 =head2 Delimited blocks
@@ -57,6 +58,42 @@ first blank line.
 =head1 Top Level Heading
 =end code
 
+=head2 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 C<#=> or C<#|>,
+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 C<#|> are attached to the code after them,
+and blocks starting with C<#=> 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 C<WHY> method can be used on these classes, roles, subroutines etc. to return the attached Pod value.
+
+=begin code :skip-test
+#| Base class for magicians
+class Magician {
+  has Int $.level;
+  has Str @.spells;
+}
+
+#| Fight mecanics
+sub duel(Magician $a, Magician $b) {
+}
+#= Magicians only, no mortals.
+
+say Magician.WHY; # OUTPUT: «Base class for magicians␤»
+say &duel.WHY.leading; # OUTPUT: «Fight mecanics␤»
+say &duel.WHY.trailing; # OUTPUT: «Magicians only, no mortals.␤»
+=end code
+
 =head1 Block types
 
 Pod offers a wide range of standard block types.