code review 88560044: doc: add release note for 'godoc -analysis'

doc: add release note for 'godoc -analysis'

	Contains a link to /lib/godoc/analysis/help.html
       which is not yet live.

[adg, 2014-06-12 00:31:51]

https://codereview.appspot.com/88560044/diff/20001/doc/go1.3.html
File doc/go1.3.html (right):

https://codereview.appspot.com/88560044/diff/20001/doc/go1.3.html#newcode190
doc/go1.3.html:190:
href='http://godoc.org/code.google.com/p/go.tools/cmd/godoc'>godoc</a>
please use " around the attribute values, as the rest of the file does

https://codereview.appspot.com/88560044/diff/20001/doc/go1.3.html#newcode192
doc/go1.3.html:192: href='http://golang.org/lib/godoc/analysis/help.html'>static
remove the domain part (make the link href="/lib/godoc/analysis/help.html") and
you can submit this right away.

[r, 2014-06-12 00:40:07]

https://codereview.appspot.com/88560044/diff/20001/doc/go1.3.html
File doc/go1.3.html (right):

https://codereview.appspot.com/88560044/diff/20001/doc/go1.3.html#newcode189
doc/go1.3.html:189: When invoked with the <code>-analysis</code> flag, <a
no indentation please. mimic the text around your change.

also i don't like the hanging <a. again, mimic the surrounds. long lines don't
matter.

https://codereview.appspot.com/88560044/diff/20001/doc/go1.3.html#newcode193
doc/go1.3.html:193: analysis</a> of the code it indexes, facilitating code
comprehension
facilitating is barely a word and doesn't say what happens. how about something
like,
"decorates the output with links representing semantic properties of the code"
or some such.

and that raises the issue of where any of this is documented, which should be
cited here. but that shouldn't hold up a release.

[adonovan, 2014-06-12 01:41:53]

https://codereview.appspot.com/88560044/diff/20001/doc/go1.3.html
File doc/go1.3.html (right):

https://codereview.appspot.com/88560044/diff/20001/doc/go1.3.html#newcode189
doc/go1.3.html:189: When invoked with the <code>-analysis</code> flag, <a
On 2014/06/12 00:40:07, r wrote:
> no indentation please. mimic the text around your change.
> 
> also i don't like the hanging <a. again, mimic the surrounds. long lines don't
> matter.

Done.

https://codereview.appspot.com/88560044/diff/20001/doc/go1.3.html#newcode190
doc/go1.3.html:190:
href='http://godoc.org/code.google.com/p/go.tools/cmd/godoc'>godoc</a>
On 2014/06/12 00:31:51, adg wrote:
> please use " around the attribute values, as the rest of the file does

Done.

https://codereview.appspot.com/88560044/diff/20001/doc/go1.3.html#newcode192
doc/go1.3.html:192: href='http://golang.org/lib/godoc/analysis/help.html'>static
On 2014/06/12 00:31:51, adg wrote:
> remove the domain part (make the link href="/lib/godoc/analysis/help.html")
and
> you can submit this right away.

Done.

https://codereview.appspot.com/88560044/diff/20001/doc/go1.3.html#newcode193
doc/go1.3.html:193: analysis</a> of the code it indexes, facilitating code
comprehension
On 2014/06/12 00:40:07, r wrote:
> facilitating is barely a word and doesn't say what happens. how about
something
> like,
> "decorates the output with links representing semantic properties of the code"
> or some such.

Done.  It now reads:

The results of analysis are presented in both the source view and the
package documentation view, and include the relationships 
between definitions and references;
between types and their methods;
between interfaces and their implementions;
between send and receive operations on channels;
between functions and their callers;
between call sites and their callees;
and the call graph of each package.


> and that raises the issue of where any of this is documented, which should be
> cited here. but that shouldn't hold up a release.

It is amply documented at the page linked to  on L192, which isn't live yet, but
can be browsed in raw form here:
https://code.google.com/p/go/source/browse/godoc/static/analysis/help.html?re...

[r, 2014-06-12 02:49:59]

LGTM if adg is happy

https://codereview.appspot.com/88560044/diff/40001/doc/go1.3.html
File doc/go1.3.html (right):

https://codereview.appspot.com/88560044/diff/40001/doc/go1.3.html#newcode312
doc/go1.3.html:312: and the call graph of each package.
if it's well documented elsewhere, this can just be a couple of nice examples
and a "and so on". but if you'd like to leave this full list, that's ok.

but reverse it for readability:

includes the call graph of the package and relationships between....

[adonovan, 2014-06-12 02:57:09]

https://codereview.appspot.com/88560044/diff/40001/doc/go1.3.html
File doc/go1.3.html (right):

https://codereview.appspot.com/88560044/diff/40001/doc/go1.3.html#newcode312
doc/go1.3.html:312: and the call graph of each package.
On 2014/06/12 02:49:59, r wrote:
> if it's well documented elsewhere, this can just be a couple of nice examples
> and a "and so on". but if you'd like to leave this full list, that's ok.

Thanks, I'd prefer to keep it.


> but reverse it for readability:
> 
> includes the call graph of the package and relationships between....

Good idea; done.

[r, 2014-06-12 04:06:14]

https://codereview.appspot.com/88560044/diff/60001/doc/go1.3.html
File doc/go1.3.html (right):

https://codereview.appspot.com/88560044/diff/60001/doc/go1.3.html#newcode312
doc/go1.3.html:312: between call sites and their callees.
you only need the first 'between' now

[adonovan, 2014-06-12 13:46:43]

https://codereview.appspot.com/88560044/diff/60001/doc/go1.3.html
File doc/go1.3.html (right):

https://codereview.appspot.com/88560044/diff/60001/doc/go1.3.html#newcode312
doc/go1.3.html:312: between call sites and their callees.
On 2014/06/12 04:06:14, r wrote:
> you only need the first 'between' now

Indeed.  Done.

[adonovan, 2014-06-12 14:08:53]

Hello r@golang.org, adg@golang.org (cc: golang-codereviews@googlegroups.com),

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

[adonovan, 2014-06-12 14:09:01]

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

       doc: add release note for 'godoc -analysis'

	Contains a link to /lib/godoc/analysis/help.html
       which is not yet live.

LGTM=r
R=r, adg
CC=golang-codereviews
https://codereview.appspot.com/88560044

[gobot, 2014-06-12 14:32:06]

This CL appears to have broken the nacl-amd64p32 builder.
See http://build.golang.org/log/6be8e51639bd30d97d270be5c3634f616c5d7cfe

[r, 2014-06-12 15:30:32]

LGTM ship it

[adg, 2014-06-13 05:30:58]

LGTM