slices: misc improvements to godoc #30
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
In many cases the godoc for slices was referencing "arr", but all functions use "items" as the slice name. "arr" is also misleading since users could assume this refers to the backing array.
- Add full stops to sentences. - Remove the occasional inconsistent use of `code formatting`, which is not typically rendered in godoc. - Add particles to sentences where appropriate to improve readability.
- Add full stops to sentences. - Add particles to sentences where appropriate to improve readability. - Always describe the primary slice as `items` to match the argument names. - Reword some godoc to improve grammar or clarify behaviour.
I haven't convinced myself that these are actually cartesian product implementations, but my math brain hasn't been used in a while so I have focused on the godoc.
Zip can be a little confusing without an example, so I have tried to add a concise explanation and example to the godoc. The `ExampleZip()` contains excellent examples so perhaps the docs should refer people to that instead?
dwurf
changed the title
|
Thank you! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is my attempt to improve the godoc for the
slicespackage. I have been pretty heavy-handed in some places so I've tried to split the PR up into useful commits.The general thrust of it is to try to improve spelling, grammar, consistency and readability. It started as just a fix to the spelling in
SortBy, then I noticed an inconsistent use ofarr,itemsandthe given sliceto refer to the (primary) slice for each function.arrclearly does not match any of the argument names, and may mislead the user into thinking they are modifying the backing array.the given sliceonly makes sense when there is one input slice, and is a bit more wordy than the other two options.itemsis the correct parameter name and is unambiguous when there are multiple slices, but it reads strangely in some places.I ended up settling for using
itemsalmost everywhere, although for me it was a bit of a coin toss which way was better.Some other consistency changes:
code blocksin paragraphs do not get rendered as godoc e.g. see here, and this was inconsistently sprinkled into some function docs. I opted to remove this, although it might be clearer to lean into this even if it isn't rendered as it would help with clarity in some cases where theitemsgrammar is ambiguous.frather thanFto describe function arguments.For a couple of functions I've taken a stab at rewriting the godoc entirely to make it clearer. I think this helps a lot in cases like
Rejectwhere you had to go and look at the docs forFilterto get a complete picture of what the function was doing, and even more so forScanwhere the docs were explaining only how it is different fromReduce, which is itself a difficult to explain operation.