From 984ad94dc60d720ac2feb919f7615e15d2ad8e5a Mon Sep 17 00:00:00 2001
From: JJ Merelo <jjmerelo@gmail.com>
Date: Mon, 20 Aug 2018 18:55:09 +0200
Subject: [PATCH] Adds a simple note on the behavior of is pure on multis

Basically specifying that this could change in the future, if
rakudo/rakudo#2215 is solved. This solves #2215
---
 doc/Type/Routine.pod6 | 36 +++++++++++++++++++-----------------
 1 file changed, 19 insertions(+), 17 deletions(-)

diff --git a/doc/Type/Routine.pod6 b/doc/Type/Routine.pod6
index 5d00f8682..28ea7b9c7 100644
--- a/doc/Type/Routine.pod6
+++ b/doc/Type/Routine.pod6
@@ -31,9 +31,9 @@ called.
     f();   # OUTPUT: «"Hello there"␤»
 
 The C<is default> trait can become very useful for debugging and other uses but
-keep in mind that it will only resolve an ambiguous dispatch between two C<Routine>s
-of the same precedence. If one of the C<Routine>s are narrower than another, then
-that one will be called. For example:
+keep in mind that it will only resolve an ambiguous dispatch between two
+C<Routine>s of the same precedence. If one of the C<Routine>s are narrower than
+another, then that one will be called. For example:
 
     =begin code
     multi sub f() is default { say "Hello there" }
@@ -44,7 +44,7 @@ that one will be called. For example:
 In this example, the C<multi> without C<is default> was called because it was
 actually narrower than the C<Sub> with it.
 
-Subroutines can also be declared C<anon>. See the L<documentation on the C<anon> declarator|/language/variables#The_anon_Declarator> for more information.
+Subroutines can also be declared C<anon>. See the L<documentation on the C<anon> declarator|/language/variables#The_anon_declarator> for more information.
 
 =head1 Methods
 
@@ -173,16 +173,9 @@ Calculating 43th prime
 Marks a subroutine as I<pure>, that is, it asserts that for the same input, it
 will always produce the same output without any additional side effects.
 
-You can mark function as pure even if they throw exceptions in edge cases,
-or if they modify temporary objects; hence the C<is pure> trait can cover
-cases that the compiler cannot deduce on its own. On the other hand, you might
-not want to constant-fold functions that produce a large return value (such
-as the string or list repetition operators, infix C<x> and C<xx>) even if they
-are pure, to avoid large precompilation files.
-
-The C<is pure> trait is a promise by the programmer to the compiler that it
-can constant-fold
-calls to such functions when the arguments are known at compile time.
+The C<is pure> trait is a promise by the programmer to the compiler that it can
+constant-fold calls to such functions when the arguments are known at compile
+time.
 
     sub syllables() is pure {
         say "Generating syllables";
@@ -190,6 +183,13 @@ calls to such functions when the arguments are known at compile time.
         return  @vowels.append: <k m n sh d r t y> X~ @vowels;
     }
 
+You can mark function as pure even if they throw exceptions in edge cases
+or if they modify temporary objects; hence the C<is pure> trait can cover
+cases that the compiler cannot deduce on its own. On the other hand, you might
+not want to constant-fold functions that produce a large return value (such
+as the string or list repetition operators, infix C<x> and C<xx>) even if they
+are pure, to avoid large precompilation files.
+
 To see it an action with a particular compiler you can try this example:
 
     =begin code :preamble<sub syllables {}>
@@ -218,6 +218,8 @@ where the result is discarded) may lead to a warning. The code
     say "anything";
     # WARNING: «Useless use of "double(21)" in expression "double(21)" in sink context (line 2)»
 
+If you want to apply this trait to a C<multi>, you need to apply it to the
+C<proto>; it will not work otherwise, at least in versions 2018.08 and below.
 
 =head2 trait is rw
 
@@ -253,8 +255,8 @@ produces
 ("some" => {"key" => [Any, [Any, Any, "autovivified"]]}).hash
 =end code
 
-Note that C<return> marks return values as read only; if you need an early
-exit from an C<is rw> routine, you have to use X<C<return-rw>|return-rw> instead.
+Note that C<return> marks return values as read only; if you need an early exit
+from an C<is rw> routine, you have to use X<C<return-rw>|return-rw> instead.
 
 =head2 trait is export
 
@@ -276,7 +278,7 @@ say double 21;      # 42
 From inside another file you'd say C<use Foo;> to load a module and import the
 exported functions.
 
-See L<Exporting and Selective Importing Modules|/language/modules#Exporting_and_Selective_Importing>
+See L<Exporting and Selective Importing Modules|/language/modules#Exporting_and_selective_importing>
 for more details.
 
 =head2 trait is DEPRECATED