Skip to content
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

Jump to bottom

strings: Index: confusing documentation #19039

Closed
gtownsend opened this issue Feb 11, 2017 · 2 comments
Closed

strings: Index: confusing documentation #19039

gtownsend opened this issue Feb 11, 2017 · 2 comments
Labels
Documentation FrozenDueToAge
Milestone
Go1.9

Comments

@gtownsend
Copy link

In the documentation of the function Index, in package strings:
(referencing https://golang.org/pkg/strings/#Index as of 11 Feb 2017)

I find the use of the identifier "sep", in the description of func Index, to be confusing. On first reading I interpreted it to mean that Index would find the first occurrence in s of any of a set of "separator" characters. I suggest renaming "sep" to "substr", which would be consistent with strings.Contains.

A similar argument would apply to strings.Count and strings.LastIndex. However, the use of "sep" in strings.Join is clear as currently written.

The several Split... functions could possibly also be clarified by changing the first mention of "sep" in the prose of each to "the substring sep".
@ALTree ALTree added this to the Go1.9 milestone Feb 11, 2017
@ALTree ALTree changed the title strings.Index: confusing documentation strings: Index: confusing documentation Feb 11, 2017
@ALTree ALTree self-assigned this Feb 11, 2017
@gopherbot
Copy link

CL https://golang.org/cl/36874 mentions this issue.

@ALTree
Copy link
Member

ALTree commented Feb 11, 2017

Thanks for the report. I did not address this part

The several Split... functions could possibly also be clarified by changing the first mention of "sep" in the prose of each to "the substring sep".

in my patch because I read the documentation and I think it's clear enough. The use of sep as parameter name in Split is fine, and when sep is actually a set of separators we usually specify it, so just leaving it as "Split slices s into all substrings separated by sep" should be ok, I don't think adding "substring" before "sep" would make it clearer.

@golang golang locked and limited conversation to collaborators Feb 11, 2018
@rsc rsc unassigned ALTree Jun 23, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation FrozenDueToAge
Projects
None yet
Milestone
Go1.9
Development

No branches or pull requests
3 participants
@ALTree @gtownsend @gopherbot