per 4054 linked to next/last from while/until; moved return etc later

doc/Language/control.rakudoc

@@ -1071,7 +1071,9 @@ Both C<while> and C<until> can be used as statement modifiers. E. g.
    my $x = 42;
    $x-- while $x > 12
 
-Also see C<repeat/while> and C<repeat/until> below.
+See L<C<next>|#next>, L<C<last>|#last>, and related below for ways to
+fine-tune loop control.  Also see C<repeat/while> and C<repeat/until> for
+other loop syntax.
 
 All these forms may produce a return value the same way C<loop> does.
 
@@ -1124,59 +1126,6 @@ is evaluated at the end of the loop, even if it appears at the front.
 
 All these forms may produce a return value the same way C<loop> does.
 
-=head1 X<return|Control flow,return>
-
-The sub C<return> will stop execution of a subroutine or method, run all
-relevant L<phasers|/language/phasers#Block_phasers> and provide the
-given return value to the caller. The default return value is L<C<Nil>|/type/Nil>. If
-a return L<type constraint|/language/signatures#Constraining_return_types> is
-provided it will be checked unless the return value is L<C<Nil>|/type/Nil>. If the
-type check fails the exception
-L<C<X::TypeCheck::Return>|/type/X::TypeCheck::Return> is thrown. If it
-passes a control exception is raised and can be caught with
-L<CONTROL|/language/phasers#CONTROL>.
-
-Any C<return> in a block is tied to the first L<C<Routine>|/type/Routine> in the outer
-lexical scope of that block, no matter how deeply nested. Please note
-that a C<return> in the root of a package will fail at runtime. A
-C<return> in a block that is evaluated lazily (e.g. inside C<map>) may
-find the outer lexical routine gone by the time the block is executed.
-In almost any case C<last> is the better alternative. Please check
-L<the functions documentation|/language/functions#Return_values> for
-more information on how return values are handled and produced.
-
-=head1 X<return-rw|Control flow,return-rw>
-
-The sub C<return> will return values, not containers. Those are
-immutable and will lead to runtime errors when attempted to be mutated.
-
-    sub s(){ my $a = 41; return $a };
-    say ++s();
-    CATCH { default { say .^name, ': ', .Str } };
-    # OUTPUT: «X::Multi::NoMatch.new(dispatcher …
-
-To return a mutable container, use C<return-rw>.
-
-    sub s(){ my $a = 41; return-rw $a };
-    say ++s();
-    # OUTPUT: «42␤»
-
-The same rules as for C<return> regarding phasers and control exceptions apply.
-
-=head1 X<fail|Control flow,fail>
-
-Leaves the current routine and returns the provided
-L<C<Exception>|/type/Exception> or L<C<Str>|/type/Str> wrapped inside a
-L<C<Failure>|/type/Failure>, after all relevant
-L<phasers|/language/phasers#Block_phasers> are executed. If the caller
-activated fatal exceptions via the pragma C<use fatal;>, the exception is
-thrown instead of being returned as a L<C<Failure>|/type/Failure>.
-
-    sub f { fail "WELP!" };
-    say f;
-    CATCH { default { say .^name, ': ', .Str } }
-    # OUTPUT: «X::AdHoc: WELP!␤»
-
 =head1 X<once|Control flow,once>
 
 A block or statement prefixed with C<once> will be executed exactly once,
@@ -1389,4 +1338,58 @@ for 1..5 -> $current-level {
     }
 }
 # OUTPUT: «Entering #1... Entering #2... Entering #3... Entering #3... Entering #4... Entering #5... Entering #5... »
+
+=head1 X<return|Control flow,return>
+
+The sub C<return> will stop execution of a subroutine or method, run all
+relevant L<phasers|/language/phasers#Block_phasers> and provide the
+given return value to the caller. The default return value is L<C<Nil>|/type/Nil>. If
+a return L<type constraint|/language/signatures#Constraining_return_types> is
+provided it will be checked unless the return value is L<C<Nil>|/type/Nil>. If the
+type check fails the exception
+L<C<X::TypeCheck::Return>|/type/X::TypeCheck::Return> is thrown. If it
+passes a control exception is raised and can be caught with
+L<CONTROL|/language/phasers#CONTROL>.
+
+Any C<return> in a block is tied to the first L<C<Routine>|/type/Routine> in the outer
+lexical scope of that block, no matter how deeply nested. Please note
+that a C<return> in the root of a package will fail at runtime. A
+C<return> in a block that is evaluated lazily (e.g. inside C<map>) may
+find the outer lexical routine gone by the time the block is executed.
+In almost any case C<last> is the better alternative. Please check
+L<the functions documentation|/language/functions#Return_values> for
+more information on how return values are handled and produced.
+
+=head1 X<return-rw|Control flow,return-rw>
+
+The sub C<return> will return values, not containers. Those are
+immutable and will lead to runtime errors when attempted to be mutated.
+
+    sub s(){ my $a = 41; return $a };
+    say ++s();
+    CATCH { default { say .^name, ': ', .Str } };
+    # OUTPUT: «X::Multi::NoMatch.new(dispatcher …
+
+To return a mutable container, use C<return-rw>.
+
+    sub s(){ my $a = 41; return-rw $a };
+    say ++s();
+    # OUTPUT: «42␤»
+
+The same rules as for C<return> regarding phasers and control exceptions apply.
+
+=head1 X<fail|Control flow,fail>
+
+Leaves the current routine and returns the provided
+L<C<Exception>|/type/Exception> or L<C<Str>|/type/Str> wrapped inside a
+L<C<Failure>|/type/Failure>, after all relevant
+L<phasers|/language/phasers#Block_phasers> are executed. If the caller
+activated fatal exceptions via the pragma C<use fatal;>, the exception is
+thrown instead of being returned as a L<C<Failure>|/type/Failure>.
+
+    sub f { fail "WELP!" };
+    say f;
+    CATCH { default { say .^name, ': ', .Str } }
+    # OUTPUT: «X::AdHoc: WELP!␤»
+
 =end pod