code review 1738048: websocket: fix comment indentation

websocket: standardize comments (formatting was broken in godoc)

[adg, 2010-07-03 05:19:43]

Hello r, ukai@google.com (cc: golang-dev@googlegroups.com),

I'd like you to review this change.

[r, 2010-07-03 18:14:29]

i don't know what 'standardize' means and the only problem i see is incorrect
indentation on the first line or two. i think it's a godoc bug and should be
fixed there. the comments as they stand are useful unless i'm missing something.

adding gri

[adg, 2010-07-04 00:05:50]

They are useful, and the content is unchanged. "Standardize" is the wrong
word. All this patch does is fix some indentation issues and switch the
commenting style to that of every other standard library. If the latter is
unimportant to you then I can make this a much smaller change. I don't see
how it's a godoc bug, though.

Andrew

On 4 Jul 2010 04:14, <r@golang.org> wrote:
> i don't know what 'standardize' means and the only problem i see is
> incorrect indentation on the first line or two. i think it's a godoc bug
> and should be fixed there. the comments as they stand are useful unless
> i'm missing something.
>
> adding gri
>
> http://codereview.appspot.com/1738048/show

[r2, 2010-07-04 03:21:22]

On Jul 3, 2010, at 5:05 PM, Andrew Gerrand wrote:

> They are useful, and the content is unchanged. "Standardize" is the wrong
word. All this patch does is fix some indentation issues and switch the
commenting style to that of every other standard library. If the latter is
unimportant to you then I can make this a much smaller change. I don't see how
it's a godoc bug, though.

let's put this on hold until i'm back and gri has had a chance to look at it.

the godoc bug is that the whole comment is indented in the output.   otherwise,
what indentation issues are you referring to?

-rob

[adg, 2010-07-04 04:06:08]

On 4 July 2010 13:21, Rob 'Commander' Pike <r@google.com> wrote:
> let's put this on hold until i'm back and gri has had a chance to look at it.

Sure.

> the godoc bug is that the whole comment is indented in the output.  
otherwise, what indentation issues are you referring to?

The problem I'm referring to is the formatting of the example code here:
http://golang.org/pkg/websocket/#Conn.Dial

The godoc formatting rule is a simple one. Comments are formatted as
normal text, except where indented, in which case they are formatted
as code inside PRE tags. The docs for Dial (and Handle) had example
code at the same level of indentation is the general description, so
only the imports and the body of main were in pre tags. Indenting the
sample code (as is part of this CL) resolves it.

Andrew

[r2, 2010-07-04 04:25:41]

On Jul 3, 2010, at 9:05 PM, Andrew Gerrand wrote:

> On 4 July 2010 13:21, Rob 'Commander' Pike <r@google.com> wrote:
>> let's put this on hold until i'm back and gri has had a chance to look at it.
> 
> Sure.
> 
>> the godoc bug is that the whole comment is indented in the output.  
otherwise, what indentation issues are you referring to?
> 
> The problem I'm referring to is the formatting of the example code here:
> http://golang.org/pkg/websocket/#Conn.Dial
> 
> The godoc formatting rule is a simple one. Comments are formatted as
> normal text, except where indented, in which case they are formatted
> as code inside PRE tags. The docs for Dial (and Handle) had example
> code at the same level of indentation is the general description, so
> only the imports and the body of main were in pre tags. Indenting the
> sample code (as is part of this CL) resolves it.

Ah.  Then the CL description should say that (briefly) and the change could
perhaps address only that.  Given the 'standard' word and the conversion of /**/
to // comments I did not understand the point.

The change in comment style is unnecessary.

-rob

[adg, 2010-07-05 04:09:15]

Hello r, ukai (cc: golang-dev@googlegroups.com, gri),

I'd like you to review this change.

[ukai, 2010-07-06 07:13:28]

LGTM
Thanks!

[rsc1, 2010-07-12 21:24:34]

LGTM

[r, 2010-07-12 21:29:47]

http://codereview.appspot.com/1738048/diff/8001/9002
File src/pkg/websocket/server.go (right):

http://codereview.appspot.com/1738048/diff/8001/9002#newcode46
src/pkg/websocket/server.go:46: in 5.2 Sending the server's opening handshake,
4.
if you're going to unindent the other comments, you should unindent all of them

[adg, 2010-07-13 00:30:01]

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

websocket: fix comment indentation
To make code samples formatted correctly by godoc.

R=r, ukai, rsc
CC=golang-dev, gri
http://codereview.appspot.com/1738048

Committer: Andrew Gerrand <adg@golang.org>