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.
method set_why($why)
Sets the documentation for a type to $why.
method WHY()
Returns the documentation for a type.