Skip to content

Commit 81af567

Browse files
committed
Stick to actual Rakudo signatures
In these cases it's probably not so bad to have less meaningful parameter names because these subroutines just implement indirection.
1 parent 7b1ca20 commit 81af567

File tree

1 file changed

+24
-23
lines changed

1 file changed

+24
-23
lines changed

doc/Type/independent-routines.pod6

Lines changed: 24 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1200,9 +1200,9 @@ Routines that manipulate arrays and other mutable collections.
12001200
12011201
Defined as:
12021202
1203-
multi sub pop(@collection) is raw
1203+
multi sub pop(@a) is raw
12041204
1205-
Calls method C<pop> on the C<Positional> collection. That method is supposed to
1205+
Calls method C<pop> on the C<Positional> argument. That method is supposed to
12061206
remove and return the last element, or return a L<C<Failure>|/type/Failure> if
12071207
the collection is empty.
12081208
@@ -1213,9 +1213,9 @@ for an example.
12131213
12141214
Defined as:
12151215
1216-
multi sub shift(@collection) is raw
1216+
multi sub shift(@a) is raw
12171217
1218-
Calls method C<shift> on the C<Positional> collection. That method, on
1218+
Calls method C<shift> on the C<Positional> argument. That method, on
12191219
a mutable collection that actually implements it (such as an
12201220
L<C<Array>|/routine/shift#(Array)_method_shift> or a
12211221
L<C<Buf>|/routine/shift#(Buf)_method_shift>), is supposed to remove
@@ -1235,40 +1235,41 @@ say shift @a; # ERROR: «Cannot shift from an empty Array[Int]␤»
12351235
12361236
Defined as:
12371237
1238-
multi sub push(\collection, **@values is raw)
1239-
multi sub push(\collection, \arg)
1238+
multi sub push(\a, **@b is raw)
1239+
multi sub push(\a, \b)
12401240
1241-
Calls method C<push> on the collection, which is supposed to add the provided
1242-
values to the end of the collection or parts thereof. See the documentation of
1243-
the L<C<Hash> method|/routine/push#(Hash)_method_push> for an example where
1241+
Calls method C<push> on the first argument, passing the remaining arguments.
1242+
Method C<push> is supposed to add the provided values to the end of the
1243+
collection or parts thereof. See the documentation of the
1244+
L<C<Hash> method|/routine/push#(Hash)_method_push> for an example where
12441245
indirection via this subroutine can be helpful.
12451246
1246-
The C<push> method of the collection is supposed to flatten all arguments of
1247-
type C<Slip>. Therefore, if you want to implement a conforming method for a new
1248-
collection type, it should behave as if its signature was just:
1247+
The C<push> method is supposed to flatten all arguments of type C<Slip>.
1248+
Therefore, if you want to implement a conforming method for a new collection
1249+
type, it should behave as if its signature was just:
12491250
1250-
multi method push(::?CLASS:D: **@values --> ::?CLASS:D)
1251+
multi method push(::?CLASS:D: **@values is raw --> ::?CLASS:D)
12511252
12521253
Autovivification to an instance of the new type is L<provided by the default
12531254
base class|/routine/append#(Any)_method_append> if the new type implements the
12541255
C<Positional> role. If the new type is not C<Positional>, autovivification can
1255-
be implemented by an additional multi method with a signature like
1256+
be supported by an adding a multi method with a signature like
12561257
1257-
multi method push(::?CLASS:U: **@values --> ::?CLASS:D)
1258+
multi method push(::?CLASS:U: **@values is raw --> ::?CLASS:D)
12581259
12591260
=head2 sub append
12601261
12611262
Defined as:
12621263
1263-
multi sub append(\collection, **@values is raw)
1264-
multi sub append(\collection, \arg)
1264+
multi sub append(\a, **@b is raw)
1265+
multi sub append(\a, \b)
12651266
1266-
Calls method C<append> on the collection, which is supposed to add the provided
1267-
values to the end of the collection or parts thereof. Unlike method C<push>,
1268-
method C<append> should follow the L<single argument
1269-
rule|/language/functions#Slurpy_conventions>. So if you want to implement a
1270-
conforming method C<append> for a new collection type, it should behave as if
1271-
its signature was just:
1267+
Calls method C<append> on the first argument, passing the remaining arguments.
1268+
Method C<append> is supposed to add the provided values to the end of the
1269+
collection or parts thereof. Unlike method C<push>, method C<append> should
1270+
follow the L<single argument rule|/language/functions#Slurpy_conventions>. So
1271+
if you want to implement a conforming method C<append> for a new collection
1272+
type, it should behave as if its signature was just:
12721273
12731274
multi method append(::?CLASS:D: +values --> ::?CLASS:D)
12741275

0 commit comments

Comments
 (0)