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

Open
dreness opened this issue Jul 24, 2020 · 3 comments · May be fixed by #40654
Open

strings: missing docstrings for Reader methods #40381

dreness opened this issue Jul 24, 2020 · 3 comments · May be fixed by #40654

Comments

@dreness
Copy link

@dreness 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

@Yogendra0Sharma Yogendra0Sharma commented Jul 24, 2020

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 this to the Backlog milestone Jul 24, 2020
@dreness
Copy link
Author

@dreness dreness commented Jul 25, 2020

@Yogendra0Sharma sure, thanks very much :)

qbradq added a commit to qbradq/go that referenced this issue Aug 8, 2020
There is no documentation on a number of methods in the strings.Reader
struct, so this change adds documentation refering to the relavent
io.* interfaces implemented. This is consistent with pre-existing
documentation in this struct.

Fixes golang#40381
@qbradq qbradq linked a pull request that will close this issue Aug 8, 2020
@gopherbot
Copy link

@gopherbot gopherbot commented Aug 8, 2020

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

4 participants
You can’t perform that action at this time.