code review 5573068: godoc: move overview before API TOC

godoc: move overview before API TOC

Compare:
http://swtch.com/junk/regexp0.html [old]
http://swtch.com/junk/regexp.html [new]

Especially for packages with large APIs, this makes the
overview more promiment, so that it can give the appropriate
context for reading the API list.  This should help significantly
in packages with large APIs, like net, so that the first thing users
see is not a jumble of functions but an introduction to the package.

[rsc, 2012-01-25 22:39:53]

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

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

[gri, 2012-01-25 22:42:26]

LGTM

but let other weigh in
- gri

On Wed, Jan 25, 2012 at 2:39 PM,  <rsc@golang.org> wrote:
> Reviewers: adg, gri, r,
>
> Message:
> Hello adg, gri, r (cc: golang-dev@googlegroups.com),
>
> I'd like you to review this change to
> https://go.googlecode.com/hg/
>
>
> Description:
> godoc: move overview before API TOC
>
> Compare:
> http://swtch.com/junk/regexp0.html [old]
> http://swtch.com/junk/regexp.html [new]
>
> Especially for packages with large APIs, this makes the
> overview more promiment, so that it can give the appropriate
> context for reading the API list.  This should help significantly
> in packages with large APIs, like net, so that the first thing users
> see is not a jumble of functions but an introduction to the package.
>
> Please review this at http://codereview.appspot.com/5573068/
>
> Affected files:
>  M lib/godoc/package.html
>
>

[kevlar, 2012-01-25 22:53:54]

LGTM

I didn't think I'd like it, but I think it flows more nicely and will
encourage people to have good package comments.  It pairs well with the
change from two-column to verbose TOC.

[dsymonds, 2012-01-25 23:48:47]

LGTM

[adg, 2012-01-26 00:10:09]

How does text/template look? Its "overview" is more like a manual.

[r, 2012-01-26 00:34:34]

LGTM

[adg, 2012-01-26 01:31:11]

LGTM

[rog, 2012-01-26 08:54:06]

LGTM

but i'm not sure about the two links at the top of the
page. the Overview link seems redundant, because
the overview is right there.

the API link could perhaps be slightly more verbose;
"Index", perhaps, losing the TLA?
or even "Index of types, constants and functions".

[rsc, 2012-01-26 15:54:47]

Changed API to Index.

[rsc, 2012-01-26 18:02:07]

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

godoc: move overview before API TOC

Compare:
http://swtch.com/junk/regexp0.html [old]
http://swtch.com/junk/regexp.html [new]

Especially for packages with large APIs, this makes the
overview more promiment, so that it can give the appropriate
context for reading the API list.  This should help significantly
in packages with large APIs, like net, so that the first thing users
see is not a jumble of functions but an introduction to the package.

R=adg, gri, r, kevlar, dsymonds, rogpeppe
CC=golang-dev
http://codereview.appspot.com/5573068