code review 5544073: image/color: simplify documentation

image/color: simplify documentation

[crawshaw1, 2012-01-15 23:34:48]

Hello nigeltao@golang.org (cc: golang-dev@googlegroups.com),

I'd like you to review this change to
https://go.googlecode.com/hg/

[dsymonds, 2012-01-15 23:36:13]

Wouldn't it be better to fix godoc instead?

[crawshaw1, 2012-01-15 23:43:12]

On Mon, Jan 16, 2012 at 10:36 AM, David Symonds <dsymonds@golang.org> wrote:
> Wouldn't it be better to fix godoc instead?

I cannot decide if godoc is broken.

[dsymonds, 2012-01-15 23:48:07]

On Mon, Jan 16, 2012 at 10:43 AM, David Crawshaw <crawshaw@google.com> wrote:

> On Mon, Jan 16, 2012 at 10:36 AM, David Symonds <dsymonds@golang.org> wrote:
>> Wouldn't it be better to fix godoc instead?
>
> I cannot decide if godoc is broken.

A mail to golang-dev/golang-nuts would be a good way to start that discussion.

[crawshaw1, 2012-01-15 23:57:28]

On Mon, Jan 16, 2012 at 10:48 AM, David Symonds <dsymonds@golang.org> wrote:
> On Mon, Jan 16, 2012 at 10:43 AM, David Crawshaw <crawshaw@google.com> wrote:
>
>> On Mon, Jan 16, 2012 at 10:36 AM, David Symonds <dsymonds@golang.org> wrote:
>>> Wouldn't it be better to fix godoc instead?
>>
>> I cannot decide if godoc is broken.
>
> A mail to golang-dev/golang-nuts would be a good way to start that discussion.

Done. However, I think this CL stands on its own. There are other
examples of sets of similar public variables not having a doc line
each (e.g. net/http), and I think the godoc is much prettier if the
Model implementations are in one variable block.

[dsymonds, 2012-01-16 00:09:00]

On Mon, Jan 16, 2012 at 10:57 AM, David Crawshaw <crawshaw@google.com> wrote:

> Done. However, I think this CL stands on its own. There are other
> examples of sets of similar public variables not having a doc line
> each (e.g. net/http), and I think the godoc is much prettier if the
> Model implementations are in one variable block.

The question is though, would you make the change in this CL if godoc
behaved differently? We shouldn't distort code just because a tool
mishandles it.


Dave.

[adg, 2012-01-16 00:11:02]

On 16 January 2012 11:09, David Symonds <dsymonds@golang.org> wrote:
> On Mon, Jan 16, 2012 at 10:57 AM, David Crawshaw <crawshaw@google.com> wrote:
>
>> Done. However, I think this CL stands on its own. There are other
>> examples of sets of similar public variables not having a doc line
>> each (e.g. net/http), and I think the godoc is much prettier if the
>> Model implementations are in one variable block.
>
> The question is though, would you make the change in this CL if godoc
> behaved differently? We shouldn't distort code just because a tool
> mishandles it.

I agree with Crawshaw here. The code is definitely better now
regardless of godoc.

Andrew

[dsymonds, 2012-01-16 00:12:42]

On Mon, Jan 16, 2012 at 11:10 AM, Andrew Gerrand <adg@golang.org> wrote:

> I agree with Crawshaw here. The code is definitely better now
> regardless of godoc.

I haven't looked closely at the code. If it looks better regardless of
godoc changes, that's fine with me.

[nigeltao, 2012-01-16 03:35:16]

http://codereview.appspot.com/5544073/diff/4003/src/pkg/image/color/color.go
File src/pkg/image/color/color.go (right):

http://codereview.appspot.com/5544073/diff/4003/src/pkg/image/color/color.go#...
src/pkg/image/color/color.go:167: func modelRGBA(c Color) Color {
s/modelRGBA/rgbaModel/ and similarly elsewhere.

[crawshaw1, 2012-01-16 04:34:45]

http://codereview.appspot.com/5544073/diff/4003/src/pkg/image/color/color.go
File src/pkg/image/color/color.go (right):

http://codereview.appspot.com/5544073/diff/4003/src/pkg/image/color/color.go#...
src/pkg/image/color/color.go:167: func modelRGBA(c Color) Color {
On 2012/01/16 03:35:17, nigeltao wrote:
> s/modelRGBA/rgbaModel/ and similarly elsewhere.

Done. (I was avoiding rGBAModel the hard way.)

[nigeltao, 2012-01-16 05:00:27]

LGTM.

[nigeltao, 2012-01-16 05:02:51]

*** Submitted as http://code.google.com/p/go/source/detail?r=c2f40bab9029 ***

image/color: simplify documentation

R=nigeltao, dsymonds, adg
CC=golang-dev
http://codereview.appspot.com/5544073

Committer: Nigel Tao <nigeltao@golang.org>