code review 5454044: doc/go1: map deletion

doc/go1: map deletion
This CL is in part a proposal for how to write these sections:
- Brief discussion of change
- No attempt to analyze the thinking about it
- Old code
- New code, runnable if possible
- How to update old programs

[r, 2011-12-07 22:55:22]

Hello golang-dev@googlegroups.com,

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

[remyoudompheng, 2011-12-07 23:08:19]

http://codereview.appspot.com/5454044/diff/1/doc/go1.html
File doc/go1.html (right):

http://codereview.appspot.com/5454044/diff/1/doc/go1.html#newcode42
doc/go1.html:42: <h3 id="map_delettion">Deleting from maps</h3>
Did you mean "map_deletion" with one 't'?

http://codereview.appspot.com/5454044/diff/1/doc/go1.html#newcode72
doc/go1.html:72: when it is clear that the ignored value can be safely discarded
from the program and false refers to the predefined boolean constant.
why isn't this line wrapped like the others?

[r, 2011-12-08 00:02:31]

Hello golang-dev@googlegroups.com, remyoudompheng@gmail.com (cc:
golang-dev@googlegroups.com),

Please take another look.

[gri, 2011-12-08 00:07:30]

LGTM

http://codereview.appspot.com/5454044/diff/4001/doc/progs/go1.go
File doc/progs/go1.go (right):

http://codereview.appspot.com/5454044/diff/4001/doc/progs/go1.go#newcode1
doc/progs/go1.go:1: // Copyright 2009 The Go Authors. All rights reserved.
2011

[adg, 2011-12-08 00:10:32]

LGTM

http://codereview.appspot.com/5454044/diff/4001/doc/go1.html
File doc/go1.html (right):

http://codereview.appspot.com/5454044/diff/4001/doc/go1.html#newcode53
doc/go1.html:53: This syntax had a number of minor problems and is being
replaced.
"has been replaced" ? You could probably lose the sentence entirely, though.

[r, 2011-12-08 00:11:20]

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

doc/go1: map deletion
This CL is in part a proposal for how to write these sections:
- Brief discussion of change
- No attempt to analyze the thinking about it
- Old code
- New code, runnable if possible
- How to update old programs

R=golang-dev, remyoudompheng, gri, adg
CC=golang-dev
http://codereview.appspot.com/5454044

[r2, 2011-12-08 00:15:35]

On Dec 7, 2011, at 4:10 PM, adg@golang.org wrote:

> LGTM
> 
> 
> http://codereview.appspot.com/5454044/diff/4001/doc/go1.html
> File doc/go1.html (right):
> 
> http://codereview.appspot.com/5454044/diff/4001/doc/go1.html#newcode53
> doc/go1.html:53: This syntax had a number of minor problems and is being
> replaced.
> "has been replaced" ? You could probably lose the sentence entirely,
> though.

sure. i'll do that in the next round. it's early yet.

[adg, 2011-12-08 00:22:11]

On 8 December 2011 11:15, Rob 'Commander' Pike <r@google.com> wrote:
> sure. i'll do that in the next round. it's early yet.

No worries. Just want to set the right tone from the beginning. I
think all the changes should be specified in the past tense, as they
have happened, and that we should minimize the editorializing as to
why we made the changes. Perhaps we could add a section to the doc -
FAQ about these changes - to separate the what from the why.

Andrew

[r2, 2011-12-08 00:24:25]

On Dec 7, 2011, at 4:21 PM, Andrew Gerrand wrote:

> On 8 December 2011 11:15, Rob 'Commander' Pike <r@google.com> wrote:
>> sure. i'll do that in the next round. it's early yet.
> 
> No worries. Just want to set the right tone from the beginning. I
> think all the changes should be specified in the past tense, as they
> have happened, and that we should minimize the editorializing as to
> why we made the changes. Perhaps we could add a section to the doc -
> FAQ about these changes - to separate the what from the why.

I'd just have a separate doc, except we already have one and I see no reason to
write another.

-rob

[adg, 2011-12-08 00:27:34]

On 8 December 2011 11:24, Rob 'Commander' Pike <r@google.com> wrote:
>
> On Dec 7, 2011, at 4:21 PM, Andrew Gerrand wrote:
>
>> On 8 December 2011 11:15, Rob 'Commander' Pike <r@google.com> wrote:
>>> sure. i'll do that in the next round. it's early yet.
>>
>> No worries. Just want to set the right tone from the beginning. I
>> think all the changes should be specified in the past tense, as they
>> have happened, and that we should minimize the editorializing as to
>> why we made the changes. Perhaps we could add a section to the doc -
>> FAQ about these changes - to separate the what from the why.
>
> I'd just have a separate doc, except we already have one and I see no reason
to write another.

Sure, well we should either convert the existing doc to html and
include it, or link to the google doc.

[rsc, 2011-12-08 02:11:29]

LGTM

I agree about describing Go 1 as though it were done
(not future tense).  I like the updating sections.
The id= could be even shorter: delete, init, equal, etc.
I expect to type these URLs quite a bit, and
http://golang.org/doc/go1.html#delete is
easier to remember than the exact spelling of
http://golang.org/doc/go1.html#map_deletion.
Picky, I know.

Russ