A trait is so much more than a funky sub

[JJ]

The problem

The section that deals with it says

Despite its funky syntax, a trait is just a normal Sub

It's definitely defined that way, but there should be much more to it.

Also, the specific page on traits describes them as compiler hooks. Can't see how this describes the way the work. They attach a property to the container at compile time, but that precise description is clearer than "compiler hooks", from my POV

Suggestions

Examples should describe #1748 . Meaningful examples from actual use cases should be used.

[raiph]

Despite its funky syntax, a trait is just a normal Sub

It's definitely defined that way, but there should be much more to it.

Sure, but don't lose that sentence, or something close to it, because a trait is just a normal Sub with a funny name, and it's helpful to say so.

Also, the specific page on traits describes them as compiler hooks. Can't see how this describes the way the work. They attach a property to the container at compile time, but that precise description is clearer than "compiler hooks", from my POV

They don't necessarily attach anything to any container at compile-time. One large class of use would be to merely check things. Another would be to log some data somewhere. Or anything else that it makes sense to do. They're just, well, compiler hooks. This could make sense:

my $var is tracked; # add $var to list of variables tracked by some tracer

Traits can do anything.

The trait logic is something like that, as part of a statement declaring a named construct (variable, class, routine, enum, etc.), one of a fixed range of trait verbs (is, does, will, etc.) can appear immediately following the name, with a single arbitrary pair (with the preceding : omitted) immediately following the verb. When the compiler encounters such a verb clause, it presumes the verb is the name of a subroutine named trait_mod:<verb>, and calls it, passing the pair as a named argument, and, as the only positional argument, the compiler's data structure corresponding to the construct that's just been declared.

Whether the compiler passes a mutable data structure to the trait routine is entirely up to the compiler.

What the trait does is entirely up to the imagination and discipline of the trait author. For example, typically it's declared as a multi so it's sociable (plays nicely with others).