From: Russ Cox <rsc@golang.org>
Date: Thu, 26 Jan 2012 18:02:03 +0000 (-0500)
Subject: godoc: move overview before API TOC
X-Git-Tag: weekly.2012-01-27~12
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=71b1c6d3c98b0f34070be4c8f5e9d4c0cb2731ac;p=gostls13.git

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
https://golang.org/cl/5573068
---

diff --git a/lib/godoc/package.html b/lib/godoc/package.html
index 4aa77be88e..c7a01a877e 100644
--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -3,118 +3,121 @@
 	Use of this source code is governed by a BSD-style
 	license that can be found in the LICENSE file.
 -->
-{{if .IsPkg}}
-<!-- Table of contents; must be named manual-nav to turn off auto nav. -->
-<div id="manual-nav">
 {{with .PDoc}}
-	<dl>
-	<dd><a href="#Overview">Overview</a></dd>
-	{{if .Consts}}
-		<dd><a href="#Constants">Constants</a></dd>
-	{{end}}
-	{{if .Vars}}
-		<dd><a href="#Variables">Variables</a></dd>
-	{{end}}
-	{{range .Funcs}}
-		{{$name_html := html .Name}}
-		<dd><a href="#{{$name_html}}">{{node_html .Decl $.FSet}}</a></dd>
-	{{end}}
-	{{range .Types}}
-		{{$tname_html := html .Name}}
-		<dd><a href="#{{$tname_html}}">type {{$tname_html}}</a></dd>
-		{{range .Funcs}}
-			{{$name_html := html .Name}}
-			<dd>&nbsp; &nbsp; <a href="#{{$name_html}}">{{node_html .Decl $.FSet}}</a></dd>
-		{{end}}
-		{{range .Methods}}
-			{{$name_html := html .Name}}
-			<dd>&nbsp; &nbsp; <a href="#{{$tname_html}}.{{$name_html}}">{{node_html .Decl $.FSet}}</a></dd>
-		{{end}}
-	{{end}}
-	{{if .Bugs}}
-		<dd><a href="#Bugs">Bugs</a></dd>
-	{{end}}
-	</dl>
-{{end}}
-</div>
-{{end}}
-
-<!-- Main page -->		
-{{with .PAst}}
-	<pre>{{node_html . $.FSet}}</pre>
-{{end}}
-{{with .PDoc}}
-	<h2 id="Overview">Overview</h2>
-	<!-- The package's Name is printed as title by the top-level template -->
-	{{if $.IsPkg}}
-		<p><code>import "{{html .ImportPath}}"</code></p>
-	{{end}}
-	{{comment_html .Doc}}
 	{{if $.IsPkg}}
-		{{with .Filenames}}
-			<h4>Package files</h4>
-			<p>
-			<span style="font-size:90%">
+		<div id="short-nav">
+			<dl>
+			<dd><code>import "{{html .ImportPath}}"</code></dd>
+			</dl>
+			<dl>
+			<dd><a href="#Overview">Overview</a></dd>
+			<dd><a href="#Index">Index</a></dd>
+			</dl>
+		</div>
+		<h2 id="Overview">Overview</h2>
+		<!-- The package's Name is printed as title by the top-level template -->
+		{{comment_html .Doc}}
+	
+		<h2 id="Index">Index</h2>
+		<!-- Table of contents for API; must be named manual-nav to turn off auto nav. -->
+		<div id="manual-nav">
+			<dl>
+			{{if .Consts}}
+				<dd><a href="#Constants">Constants</a></dd>
+			{{end}}
+			{{if .Vars}}
+				<dd><a href="#Variables">Variables</a></dd>
+			{{end}}
+			{{range .Funcs}}
+				{{$name_html := html .Name}}
+				<dd><a href="#{{$name_html}}">{{node_html .Decl $.FSet}}</a></dd>
+			{{end}}
+			{{range .Types}}
+				{{$tname_html := html .Name}}
+				<dd><a href="#{{$tname_html}}">type {{$tname_html}}</a></dd>
+				{{range .Funcs}}
+					{{$name_html := html .Name}}
+					<dd>&nbsp; &nbsp; <a href="#{{$name_html}}">{{node_html .Decl $.FSet}}</a></dd>
+				{{end}}
+				{{range .Methods}}
+					{{$name_html := html .Name}}
+					<dd>&nbsp; &nbsp; <a href="#{{$tname_html}}.{{$name_html}}">{{node_html .Decl $.FSet}}</a></dd>
+				{{end}}
+			{{end}}
+			{{if .Bugs}}
+				<dd><a href="#Bugs">Bugs</a></dd>
+			{{end}}
+			<dd>
+			{{with .Filenames}}
+				<h4>Package files</h4>
+				<p>
+				<span style="font-size:90%">
+				{{range .}}
+					<a href="/{{.|srcLink}}">{{.|filename|html}}</a>
+				{{end}}
+				</span>
+				</p>
+			{{end}}
+			</dd>
+		</dl>
+	
+		{{with .Consts}}
+			<h2 id="Constants">Constants</h2>
 			{{range .}}
-				<a href="/{{.|srcLink}}">{{.|filename|html}}</a>
+				{{comment_html .Doc}}
+				<pre>{{node_html .Decl $.FSet}}</pre>
 			{{end}}
-			</span>
-			</p>
-		{{end}}
-	{{end}}
-	{{with .Consts}}
-		<h2 id="Constants">Constants</h2>
-		{{range .}}
-			{{comment_html .Doc}}
-			<pre>{{node_html .Decl $.FSet}}</pre>
 		{{end}}
-	{{end}}
-	{{with .Vars}}
-		<h2 id="Variables">Variables</h2>
-		{{range .}}
-			{{comment_html .Doc}}
-			<pre>{{node_html .Decl $.FSet}}</pre>
-		{{end}}
-	{{end}}
-	{{range .Funcs}}
-		{{/* Name is a string - no need for FSet */}}
-		{{$name_html := html .Name}}
-		<h2 id="{{$name_html}}">func <a href="/{{posLink_url .Decl $.FSet}}">{{$name_html}}</a></h2>
-		<p><code>{{node_html .Decl $.FSet}}</code></p>
-		{{comment_html .Doc}}
-		{{example_html .Name $.Examples $.FSet}}
-	{{end}}
-	{{range .Types}}
-		{{$tname := .Name}}
-		{{$tname_html := html .Name}}
-		<h2 id="{{$tname_html}}">type <a href="/{{posLink_url .Decl $.FSet}}">{{$tname_html}}</a></h2>
-		{{comment_html .Doc}}
-		<pre>{{node_html .Decl $.FSet}}</pre>
-		{{range .Consts}}
-			{{comment_html .Doc}}
-			<pre>{{node_html .Decl $.FSet}}</pre>
-		{{end}}
-		{{range .Vars}}
-			{{comment_html .Doc}}
-			<pre>{{node_html .Decl $.FSet}}</pre>
+		{{with .Vars}}
+			<h2 id="Variables">Variables</h2>
+			{{range .}}
+				{{comment_html .Doc}}
+				<pre>{{node_html .Decl $.FSet}}</pre>
+			{{end}}
 		{{end}}
-		{{example_html $tname $.Examples $.FSet}}
 		{{range .Funcs}}
+			{{/* Name is a string - no need for FSet */}}
 			{{$name_html := html .Name}}
-			<h3 id="{{$name_html}}">func <a href="/{{posLink_url .Decl $.FSet}}">{{$name_html}}</a></h3>
+			<h2 id="{{$name_html}}">func <a href="/{{posLink_url .Decl $.FSet}}">{{$name_html}}</a></h2>
 			<p><code>{{node_html .Decl $.FSet}}</code></p>
 			{{comment_html .Doc}}
 			{{example_html .Name $.Examples $.FSet}}
 		{{end}}
-		{{range .Methods}}
-			{{$name_html := html .Name}}
-			<h3 id="{{$tname_html}}.{{$name_html}}">func ({{html .Recv}}) <a href="/{{posLink_url .Decl $.FSet}}">{{$name_html}}</a></h3>
-			<p><code>{{node_html .Decl $.FSet}}</code></p>
+		{{range .Types}}
+			{{$tname := .Name}}
+			{{$tname_html := html .Name}}
+			<h2 id="{{$tname_html}}">type <a href="/{{posLink_url .Decl $.FSet}}">{{$tname_html}}</a></h2>
 			{{comment_html .Doc}}
-			{{$name := printf "%s_%s" $tname .Name}}
-			{{example_html $name $.Examples $.FSet}}
+			<pre>{{node_html .Decl $.FSet}}</pre>
+			{{range .Consts}}
+				{{comment_html .Doc}}
+				<pre>{{node_html .Decl $.FSet}}</pre>
+			{{end}}
+			{{range .Vars}}
+				{{comment_html .Doc}}
+				<pre>{{node_html .Decl $.FSet}}</pre>
+			{{end}}
+			{{example_html $tname $.Examples $.FSet}}
+			{{range .Funcs}}
+				{{$name_html := html .Name}}
+				<h3 id="{{$name_html}}">func <a href="/{{posLink_url .Decl $.FSet}}">{{$name_html}}</a></h3>
+				<p><code>{{node_html .Decl $.FSet}}</code></p>
+				{{comment_html .Doc}}
+				{{example_html .Name $.Examples $.FSet}}
+			{{end}}
+			{{range .Methods}}
+				{{$name_html := html .Name}}
+				<h3 id="{{$tname_html}}.{{$name_html}}">func ({{html .Recv}}) <a href="/{{posLink_url .Decl $.FSet}}">{{$name_html}}</a></h3>
+				<p><code>{{node_html .Decl $.FSet}}</code></p>
+				{{comment_html .Doc}}
+				{{$name := printf "%s_%s" $tname .Name}}
+				{{example_html $name $.Examples $.FSet}}
+			{{end}}
 		{{end}}
+	{{else}}  {{/* not a package; is a command */}}
+		{{comment_html .Doc}}
 	{{end}}
+
 	{{with .Bugs}}
 		<h2 id="Bugs">Bugs</h2>
 		{{range .}}
@@ -122,6 +125,11 @@
 		{{end}}
 	{{end}}
 {{end}}
+
+{{with .PAst}}
+	<pre>{{node_html . $.FSet}}</pre>
+{{end}}
+
 {{with .PList}}
 	<h2>Other packages</h2>
 	<p>
@@ -131,6 +139,7 @@
 	{{end}}
 	</p>
 {{end}}
+
 {{with .Dirs}}
 	{{/* DirList entries are numbers and strings - no need for FSet */}}
 	<h2 id="Subdirectories">Subdirectories</h2>