Example code for `andthen` docs occasionally returns error: `Attempt to return outside of any Routine`

[jubilatious1]

Example code for andthen docs occasionally returns error: Attempt to return outside of any Routine

https://docs.raku.org/routine/andthen

sub load-data {
    rand  > .5 or return; # simulated load data failure; return Nil 
    (rand > .3 ?? 'error' !! 'good data') xx 10 # our loaded data 
}
load-data.first: /good/ andthen say "$_ is good"; # OUTPUT: «(good data is good)␤» 
 
load-data() andthen .return; # return loaded data, if it's defined 
die "Failed to load data!!";

Returns (sample):

===11/10/23 11:55:27===
Use of Nil in string context
  in block <unit> at - line 5
Failed to load data!!
  in block <unit> at - line 8

===11/10/23 11:55:32===
good data is good
Failed to load data!!
  in block <unit> at - line 8

===11/10/23 11:55:38===
Use of Nil in string context
  in block <unit> at - line 5
Attempt to return outside of any Routine
  in block <unit> at - line 7

The Attempt to return outside of any Routine error above seems to distract from the main point of the code.

[raiph]

The example is nonsense. An attempt to return outside of any Routine is always a runtime exception.

[jubilatious1]

@raiph , not a great way to treat new users--filling the andthen Docs with nonsense code instead of something they can actually learn from.

[2colours]

I'm thinking what to do about it. I don't really like the whole example (and I also don't like the last paragraph).

The banal fix would be to wrap the whole snippet into a function like analyze-and-load... but that wouldn't improve the convoluted nature of the example.

[jubilatious1]

commented on commit, otherwise looks good!