=begin pod :kind<Type> :subkind<role> :category<metamodel>

=TITLE role Metamodel::Documenting

=SUBTITLE Metarole for documenting types.

    role Metamodel::Documenting { }

I<Warning>: this role is part of the Rakudo implementation, and is not
a part of the language specification.

Type declarations may include declarator blocks (C<#|> and C<#=>), which allow
you to set the type's documentation. This can then be accessed through the
C<WHY> method on objects of that type:

=begin code :solo
#|[Documented is an example class for Metamodel::Documenting's documentation.]
class Documented { }
#=[Take a look at my WHY!]

say Documented.WHY;
# OUTPUT:
# Documented is an example class for Metamodel::Documenting's documentation.
# Take a look at my WHY!
=end code

C<Metamodel::Documenting> is what implements this behavior for types.
This example can be rewritten to use its methods explicitly like so:

=begin code :solo
BEGIN {
    our Mu constant Documented = Metamodel::ClassHOW.new_type: :name<Documented>;
    Documented.HOW.compose: Documented;
    Documented.HOW.set_why: do {
        my Pod::Block::Declarator:D $pod .= new;
        $pod._add_leading:  "Documented is an example class for Metamodel::Documenting's documentation.";
        $pod._add_trailing: "Take a look at my WHY!";
        $pod
    };
}

say Documented.HOW.WHY;
# OUTPUT:
# Documented is an example class for Metamodel::Documenting's documentation.
# Take a look at my WHY!
=end code

It typically isn't necessary to handle documentation for types directly
through their HOW like this, as C<Metamodel::Documenting>'s methods are
exposed through L<Mu|/type/Mu> via its C<WHY> and C<set_why> methods,
which are usable on types in most cases.

=head1 Methods

=head2 method set_why

    method set_why($why)

Sets the documentation for a type to C<$why>.

=head2 method WHY

    method WHY()

Returns the documentation for a type.

=end pod
