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

strings: missing docstrings for Reader methods #40381

Closed
dreness opened this issue Jul 24, 2020 · 3 comments
Closed

strings: missing docstrings for Reader methods #40381

dreness opened this issue Jul 24, 2020 · 3 comments
Labels
Documentation FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@dreness
Copy link

dreness commented Jul 24, 2020

What version of Go are you using (go version)?

❯ go version
go version go1.14 darwin/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

❯ go env | egrep 'GOARCH|GOOS'
GOARCH="amd64"
GOOS="darwin"

What did you do?

I read the strings.Reader documentation.

What did you expect to see?

I expect documentation for every function, either inline or behind a link to the appropriate base... class / interface / package (I don't know the lingo yet, that's kinda why I'm reading golang docs ;)

What did you see instead?

I see that various string.Reader functions are not documented, such as:

strings.Reader.Read
strings.Reader.ReadAt
strings.Reader.ReadByte
strings.Reader.ReadRune
strings.Reader.UnreadByte
strings.Reader.UnreadRune

... and after a bit more clicking around, my impression is that at least some of these capabilities are documented, but not in the most obvious place - for example, strings.Reader.ReadAt has a nice description under io.ReaderAt

It's not unreasonable to expect that a thorough and diligent learner could follow the path from strings.Reader.Read to strings.Reader, whose description mentions (but does not link to) io.Reader, and from there to io.ReaderAt. For the benefit of golang foreigners who air-drop in to do a quick job and then bail, please consider providing some kind of inline reference for all the relevant context for any given function or interface. Maybe that takes the form of outbound links to the relevant base reference, or maybe the documentation for the wrapped interface / function is presented inline in the docs of the wrapper (perhaps 'below the fold').

@Yogendra0Sharma
Copy link

Hi @dreness Can I take this task?

@ianlancetaylor ianlancetaylor changed the title Missing docstrings for several strings.Reader functions strings: missing docstrings for Reader methods Jul 24, 2020
@ianlancetaylor ianlancetaylor added Documentation help wanted NeedsFix The path to resolution is known, but the work has not been done. labels Jul 24, 2020
@ianlancetaylor ianlancetaylor added this to the Backlog milestone Jul 24, 2020
@dreness
Copy link
Author

dreness commented Jul 25, 2020

@Yogendra0Sharma sure, thanks very much :)

@gopherbot
Copy link

Change https://golang.org/cl/247523 mentions this issue: strings: complete documentation of strings.Reader

@golang golang locked and limited conversation to collaborators Oct 30, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants