code review 87410043: doc/effective_go: mention that b.Write is a shorthand f...

doc/effective_go: mention that b.Write is a shorthand for (&b).Write when b is addressable.

The rewrite is due to Rob.

[minux1, 2014-04-13 17:02:51]

Hello golang-codereviews@googlegroups.com,

I'd like you to review this change to
https://code.google.com/p/go

[bradfitz, 2014-04-14 20:11:11]

R=r



On Sun, Apr 13, 2014 at 10:02 AM, <minux.ma@gmail.com> wrote:

> Reviewers: golang-codereviews,
>
> Message:
> Hello golang-codereviews@googlegroups.com,
>
> I'd like you to review this change to
> https://code.google.com/p/go
>
>
> Description:
> doc/effective_go: mention that b.Write is a shorthand for (&b).Write
> when b is addressable.
>
> Please review this at https://codereview.appspot.com/87410043/
>
> Affected files (+5, -3 lines):
>   M doc/effective_go.html
>
>
> Index: doc/effective_go.html
> ===================================================================
> --- a/doc/effective_go.html
> +++ b/doc/effective_go.html
> @@ -2056,9 +2056,11 @@
>  because only <code>*ByteSlice</code> satisfies <code>io.Writer</code>.
>  The rule about pointers vs. values for receivers is that value methods
>  can be invoked on pointers and values, but pointer methods can only be
> -invoked on pointers.  This is because pointer methods can modify the
> -receiver; invoking them on a copy of the value would cause those
> -modifications to be discarded.
> +invoked on pointers (except when the value is addressable, and in that
> +case, <code>b.Write</code> is a shorthand for <code>(&amp;b).Write</code>.
> +See <a href="/ref/spec#Calls">the language specification</a> for details).
> +This is because pointer methods can modify the receiver; invoking them
> +on a copy of the value would cause those modifications to be discarded.
>  </p>
>  <p>
>  By the way, the idea of using <code>Write</code> on a slice of bytes
>
>
> --
> You received this message because you are subscribed to the Google Groups
> "golang-codereviews" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to golang-codereviews+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

[r, 2014-04-14 23:30:47]

https://codereview.appspot.com/87410043/diff/30001/doc/effective_go.html
File doc/effective_go.html (right):

https://codereview.appspot.com/87410043/diff/30001/doc/effective_go.html#newc...
doc/effective_go.html:2063: on a copy of the value would cause those
modifications to be discarded.
this is big enough to be a new paragraph.
put the </p> before the parens. then start by dropping the parens and
rearranging:

<p>
This rule arises because pointer methods can modify the receiver; invoking them
on a value would cause the method to receive a copy of the value, so any
any modifications would be discarded.
The language therefore disallows this mistake.
However, a handy exception is that when the value is addressable, the language
takes care of the common
case of calling a pointer-receiver method with a non-pointer receiver by
inserting the address operator
automatically.
In our example, the variable <code>b</code> is addressable, so we can call its
<code>Write</code> method with just <code>b.Write</code>. The compiler will
rewrite that to
<code>(&amp;b).Write</code> for us.

[minux1, 2014-04-15 06:16:48]

PTAL.

[r, 2014-04-15 07:18:08]

LGTM but perhaps someone else should sign off since it's my prose

https://codereview.appspot.com/87410043/diff/50001/doc/effective_go.html
File doc/effective_go.html (right):

https://codereview.appspot.com/87410043/diff/50001/doc/effective_go.html#newc...
doc/effective_go.html:2060: </p>
blank line please.

[bradfitz, 2014-04-15 15:53:48]

LGTM

[josharian, 2014-04-15 17:09:22]

Three suggestions, although I'll also defer to r if he's happy with it as it
stands.

https://codereview.appspot.com/87410043/diff/50001/doc/effective_go.html
File doc/effective_go.html (right):

https://codereview.appspot.com/87410043/diff/50001/doc/effective_go.html#newc...
doc/effective_go.html:2066: However, a handy exception is that when the value is
addressable, the
This sentence is a bit unwieldy. Perhaps:

"There is a handy exception. When the value..." or just "However, when the
value...".

https://codereview.appspot.com/87410043/diff/50001/doc/effective_go.html#newc...
doc/effective_go.html:2067: language takes care of the common case of calling a
pointer-receiver method
To match the phrasing above:

s/calling a pointer-receiver method with a non-pointer receiver/calling a
pointer method on a value/

And for readability, I'd suggest:

s/takes care of the common case of/enables/

[r, 2014-04-15 17:59:10]

https://codereview.appspot.com/87410043/diff/50001/doc/effective_go.html
File doc/effective_go.html (right):

https://codereview.appspot.com/87410043/diff/50001/doc/effective_go.html#newc...
doc/effective_go.html:2066: However, a handy exception is that when the value is
addressable, the
On 2014/04/15 17:09:22, josharian wrote:
> This sentence is a bit unwieldy. Perhaps:
> 
> "There is a handy exception. When the value..." or just "However, when the
> value...".

Prefer your first suggestion. It really is an exception that should be called
out as such.

https://codereview.appspot.com/87410043/diff/50001/doc/effective_go.html#newc...
doc/effective_go.html:2067: language takes care of the common case of calling a
pointer-receiver method
On 2014/04/15 17:09:22, josharian wrote:
> To match the phrasing above:
> 
> s/calling a pointer-receiver method with a non-pointer receiver/calling a
> pointer method on a value/

for true parallel structure, s/calling/invoking/

> 
> And for readability, I'd suggest:
> 
> s/takes care of the common case of/enables/

not sure about that one. it's doesn't just permit it, it actually does
something. 'enables' misses the essential point.

[minux1, 2014-04-16 04:10:29]

On 2014/04/15 17:59:10, r wrote:
>
https://codereview.appspot.com/87410043/diff/50001/doc/effective_go.html#newc...
> doc/effective_go.html:2067: language takes care of the common case of calling
a
> pointer-receiver method
> On 2014/04/15 17:09:22, josharian wrote:
> > To match the phrasing above:
> > 
> > s/calling a pointer-receiver method with a non-pointer receiver/calling a
> > pointer method on a value/
> 
> for true parallel structure, s/calling/invoking/
I'm a little confused. Are you suggesting to apply the replace to your wording
or
to josharian's?

[josharian, 2014-04-16 05:30:32]

> I'm a little confused. Are you suggesting to apply the replace to your
> wording or
> to josharian's?

I think that the suggestion was cumulative, given the comment "for
true parallel structure". If I understand correctly, I believe that
both Rob and I would be happy with:

There is a handy exception. When the value is addressable, the
language takes care of the common case of invoking a pointer method on
a value by inserting the address operator automatically.

[r, 2014-04-16 15:06:06]

Yes, that's what I was pushing for.

On Tue, Apr 15, 2014 at 10:30 PM, Josh Bleecher Snyder
<josharian@gmail.com> wrote:
>> I'm a little confused. Are you suggesting to apply the replace to your
>> wording or
>> to josharian's?
>
> I think that the suggestion was cumulative, given the comment "for
> true parallel structure". If I understand correctly, I believe that
> both Rob and I would be happy with:
>
> There is a handy exception. When the value is addressable, the
> language takes care of the common case of invoking a pointer method on
> a value by inserting the address operator automatically.

[minux1, 2014-04-17 04:49:51]

Hello golang-codereviews@googlegroups.com, bradfitz@golang.org, r@golang.org,
josharian@gmail.com (cc: golang-codereviews@googlegroups.com),

Please take another look.

[josharian, 2014-04-17 05:21:50]

LGTM

On Wednesday, April 16, 2014, <minux.ma@gmail.com> wrote:

> Hello golang-codereviews@googlegroups.com, bradfitz@golang.org,
> r@golang.org, josharian@gmail.com (cc:
> golang-codereviews@googlegroups.com),
>
> Please take another look.
>
>
> https://codereview.appspot.com/87410043/
>

[r, 2014-04-17 05:36:52]

LGTM after tweaks

https://codereview.appspot.com/87410043/diff/90001/doc/effective_go.html
File doc/effective_go.html (right):

https://codereview.appspot.com/87410043/diff/90001/doc/effective_go.html#newc...
doc/effective_go.html:2065: any modifications would be discarded.  The language
therefore disallows
move the new sentence to its own line.

https://codereview.appspot.com/87410043/diff/90001/doc/effective_go.html#newc...
doc/effective_go.html:2067: There is a handy exception. When the value is
addressable, the language
s/exception/&, though/

[minux1, 2014-04-17 05:40:22]

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

doc/effective_go: mention that b.Write is a shorthand for (&b).Write when b is
addressable.

The rewrite is due to Rob.

LGTM=r, bradfitz, josharian
R=golang-codereviews, bradfitz, r, josharian
CC=golang-codereviews
https://codereview.appspot.com/87410043