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.

Sign up for GitHub

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

image: NewUniform doesn't have documentation #38739

Closed
dmitshur opened this issue Apr 29, 2020 · 2 comments
Closed

image: NewUniform doesn't have documentation #38739

dmitshur opened this issue Apr 29, 2020 · 2 comments
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Go1.15

Comments

@dmitshur
Copy link
Contributor

The image.NewUniform function is exported and should have a comment per https://golang.org/doc/effective_go.html#commentary.

This came up when I realized it's not clear whether it's better to write image.NewUniform(c) or &image.Uniform{c}. I thought maybe image.NewUniform is deprecated like image.ZP, but that's not the case given it doesn't even have a comment. But it's not easy to feel confident using an exported method in the Go standard library when it's not documented.

https://blog.golang.org/image-draw prefers &image.Uniform{c} style, but it's also from 2011. NewUniform was renamed from NewColorImage in 2011, so it has existed for quite a while.

/cc @nigeltao @robpike
@dmitshur dmitshur added Documentation Issues describing a change to documentation. NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Apr 29, 2020
@dmitshur dmitshur added this to the Backlog milestone Apr 29, 2020
@nigeltao
Copy link
Contributor

I agree that image.NewUniform needs a doc comment. I'll send out a (trivial) CL.

As for which of image.NewUniform(c) or &image.Uniform{c} is better, I think they're equally good, similar to io.LimitReader(r, n) and &io.LimitedReader{R:r, N:n}. I wouldn't mark either of them as deprecated. In hindsight, we could have only picked one, especially as composite literals are no longer a scary and new feature, but we can't change that now.

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/230777 mentions this issue: image: add a NewUniform doc comment

@dmitshur dmitshur added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Apr 29, 2020
@dmitshur dmitshur modified the milestones: Backlog, Go1.15 Apr 29, 2020
xujianhai666 pushed a commit to xujianhai666/go-1 that referenced this issue May 21, 2020
@nigeltao @xujianhai666
image: add a NewUniform doc comment
99352a9 
Fixes golang#38739

Change-Id: I42b9b601e63ab8df69a0e5ce9bcabf75bb98d83e
Reviewed-on: https://go-review.googlesource.com/c/go/+/230777
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
@golang golang locked and limited conversation to collaborators Apr 29, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Go1.15
Development

No branches or pull requests
3 participants
@dmitshur @nigeltao @gopherbot