role Metamodel::Documenting

Metarole for documenting types.

role Metamodel::Documenting { }

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

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

#|[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!

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

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!

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

Methods§

method set_why§

method set_why($why)

Sets the documentation for a type to $why.

method WHY§

method WHY()

Returns the documentation for a type.