-
Notifications
You must be signed in to change notification settings - Fork 292
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document pop, shift, push and append more concisely #3973
Conversation
In the "Defined as" sections, use meaningful parameter names and omit multis that are implemented only for performance reasons. This should more clearly convey the intent of these routines.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Text is great, change of names is great, elimination of sub/method signatures does not match the policy we usually follow here, I'm afraid. I'd appreciate if you left them the way they are, after checking that matches the actual implementation.
doc/Type/Array.pod6
Outdated
and returns the modified array. If any argument is a C<Slip>, method C<push> | ||
will add the values produced by the argument's L<iterator|/routine/iterator>. | ||
It throws if the invocant array or a C<Slip> L<is lazy|/routine/is-lazy>. | ||
Adds the provided values to the end of the array, and returns the modified |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This explanation is clearly much clearer than the previous one; but that one could maybe be kept or moved to the end.
doc/Type/independent-routines.pod6
Outdated
Probably best thought of as a simple: | ||
|
||
sub append(\a, +b) | ||
multi sub append(\container, +values) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same as above.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same reply, which also applies to pop
and shift
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Again, not the usual policy to reinterpret the source, but to match it exactly to the extent it's possible.
As you may have understood from my other comments I question the policy of documenting all multi signatures found in the Rakudo implementation. However, I do understand that this PR is not the place to try and resolve disagreements about such policies, so I'll restore the documentation of multi signatures found in the Rakudo implementation. I'll put them in a logical order (most generic first) and I'll restore the "Probably best thought of as" signatures where the most generic signature does not convey the intent of the routine, i.e. in the documentation of |
Thanks, Peter. I really appreciate that. |
@dumarchie Re implementation of |
@lizmat, don't you agree that In my opinion, this is correct:
But this is not:
The reason that the last call to |
Well, you could argue that the latter should throw, yes, as you can only represent native ints in a native int array. |
That's not my point. In the example above,
|
But you can not push anything that's not an native int to a native int array. An itemized native int array is not a native int. So either that should throw, or DWIM. I guess we're arguing on whether DWIM isn't more of a WAT ? |
Well, my idea of DWIM is that it should be possible to |
B.t.w. there's also an issue with
|
All multi signatures found in the Rakudo implementation should be documented. Parameter names can be changed to fit the documentation.
Not everybody agreed this example was redundant.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks a lot. I really appreciate the effort you've put into this (and previous versions of this page)
The problem
In #3702 I included various signatures in "Defined as" routine introductions that were exact copies of those found in the Rakudo implementation. I now think that was not a good idea, because
Consequently, these introductions did not provide a good gist of these routines.
Solution provided
I used more meaningful parameter names and removed multi signatures that are functionally irrelevant. Additionally, I edited the documentation of these routines where it referred to parameters or I just thought it could be improved.