Intent, not syntax

[JJ]

This is something I have found quite repeatedly through the documentation, and for that matter throughout almost everything that is written for every single language: Examples usually focus on syntax, and not on intent. This is the last one I have found, but I'm sure you can think of many others: lazy 1..5 when documenting lazy. This is an absolutely correct and serviceable example. The problem is that when we are dealing with relatively uncommon features such as this one, we would avoid cargo-culting by learners by using examples that could be actually used in real-life code.
In this particular case, I guess that a sequence that needs heavy-weight computation and particularly that needs to compute every member based in the last one would be the case. This might be hard to think about, and focusing on syntax is generally OK because, after all, reference docs are not tutorials. However, in some cases, making the intent of the feature clearer would help newcomers to better understand the language and put it to use.
I'm sure you can come up with many other examples you have bumped upon; if that's the case and you can work on then (or assign them to me), that would be fine. If you think this is not a priority now or simply don't agree, I'd like to hear your opinion.

[zoffixznet]

In my experience, most "real world" examples are often convoluted and pack a lot of cruft completely unrelated to the construct presented. That's fine in blog articles and tutorials that go over each example in detail, but in docs, trying to get through 1000% more content, when all you're after is a sample of how to use the particular feature being discussed, can be daunting.

I briefly looked at Signature docs and they example showing referencing a variable from the where clause looks like this:

sub one-of-them(:$a, :$b, :$c where { $a.defined ^^ $b.defined ^^ $c.defined }) {
    $a // $b // $c
};
say one-of-them(c=>42); # OUTPUT: «42␤» 

Not only it requires knowing and understanding a rather obscure ^^ operator (which reader unfamiliar with variables-in-wheres is unlikely to know), it abuses the where clause feature (it's an only sub... just stick a die at the end of the body instead of duplicating the checks), and doesn't actually demonstrate what it does (e.g. failing typecheck).

On the other hand, a completely useless and made up example below clearly shows I can "just use" a variable in a where clause and have its value used in a typecheck. And even if a person isn't familiar with WhaterCode yet, they can surmise the meaning of * in the code, thanks to the simple math operators used and explanatory sentence printed by the routine.

sub foo($a, $b where * == $a²) { say "$b is a square of $a" }
foo 2, 3; # OUTPUT: «Constraint type check failed in binding to parameter '$b'…»

[JJ]

That example is not totally useless. An useless example would be sub foo( $a where $a eq 'bar'). That example actually shows intent: You can use this feature for arithmetic checks. I could discuss if ² falls within the "rather obscure" category (why would people know ² and not ^^?) but in general, I agree with you: the second example is much better than the first. The first one shows intent, actually, but I generally agree with you that you should avoid obscure operators, so yours is so much better.