src/pkg: make package doc comments consistently start with "Package foo".

R=rsc
CC=golang-dev
https://golang.org/cl/4442064

doc/effective_go.html

@@ -159,7 +159,7 @@ should set up the detailed documentation that follows.
 
 <pre>
 /*
-    The regexp package implements a simple library for
+    Package regexp implements a simple library for
     regular expressions.
 
     The syntax of the regular expressions accepted is:
@@ -186,7 +186,7 @@ If the package is simple, the package comment can be brief.
 </p>
 
 <pre>
-// The path package implements utility routines for
+// Package path implements utility routines for
 // manipulating slash-separated filename paths.
 </pre>
 

src/pkg/archive/tar/common.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The tar package implements access to tar archives.
+// Package tar implements access to tar archives.
 // It aims to cover most of the variations, including those produced
 // by GNU and BSD tars.
 //

src/pkg/archive/zip/reader.go

@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 /*
-The zip package provides support for reading ZIP archives.
+Package zip provides support for reading ZIP archives.
 
 See: http://www.pkware.com/documents/casestudies/APPNOTE.TXT
 

src/pkg/asn1/asn1.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The asn1 package implements parsing of DER-encoded ASN.1 data structures,
+// Package asn1 implements parsing of DER-encoded ASN.1 data structures,
 // as defined in ITU-T Rec X.690.
 //
 // See also ``A Layman's Guide to a Subset of ASN.1, BER, and DER,''

src/pkg/big/nat.go

@@ -2,11 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This file contains operations on unsigned multi-precision integers.
+// Package big implements multi-precision arithmetic (big numbers).
-// These are the building blocks for the operations on signed integers
-// and rationals.
-
-// This package implements multi-precision arithmetic (big numbers).
 // The following numeric types are supported:
 //
 //	- Int	signed integers
@@ -18,6 +14,10 @@
 //
 package big
 
+// This file contains operations on unsigned multi-precision integers.
+// These are the building blocks for the operations on signed integers
+// and rationals.
+
 import "rand"
 
 // An unsigned integer x of the form

src/pkg/bufio/bufio.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements buffered I/O.  It wraps an io.Reader or io.Writer
+// Package bufio implements buffered I/O.  It wraps an io.Reader or io.Writer
 // object, creating another object (Reader or Writer) that also implements
 // the interface but provides buffering and some help for textual I/O.
 package bufio

src/pkg/bytes/bytes.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The bytes package implements functions for the manipulation of byte slices.
+// Package bytes implements functions for the manipulation of byte slices.
-// Analogous to the facilities of the strings package.
+// It is analogous to the facilities of the strings package.
 package bytes
 
 import (

src/pkg/cmath/abs.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The cmath package provides basic constants
+// Package cmath provides basic constants and mathematical functions for
-// and mathematical functions for complex numbers.
+// complex numbers.
 package cmath
 
 import "math"

src/pkg/compress/flate/inflate.go

@@ -2,9 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The flate package implements the DEFLATE compressed data
+// Package flate implements the DEFLATE compressed data format, described in
-// format, described in RFC 1951.  The gzip and zlib packages
+// RFC 1951.  The gzip and zlib packages implement access to DEFLATE-based file
-// implement access to DEFLATE-based file formats.
+// formats.
 package flate
 
 import (

src/pkg/compress/gzip/gunzip.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The gzip package implements reading and writing of
+// Package gzip implements reading and writing of gzip format compressed files,
-// gzip format compressed files, as specified in RFC 1952.
+// as specified in RFC 1952.
 package gzip
 
 import (

src/pkg/compress/lzw/reader.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The lzw package implements the Lempel-Ziv-Welch compressed data format,
+// Package lzw implements the Lempel-Ziv-Welch compressed data format,
 // described in T. A. Welch, ``A Technique for High-Performance Data
 // Compression'', Computer, 17(6) (June 1984), pp 8-19.
 //

src/pkg/compress/zlib/reader.go

@@ -3,8 +3,8 @@
 // license that can be found in the LICENSE file.
 
 /*
-The zlib package implements reading and writing of zlib
+Package zlib implements reading and writing of zlib format compressed data,
-format compressed data, as specified in RFC 1950.
+as specified in RFC 1950.
 
 The implementation provides filters that uncompress during reading
 and compress during writing.  For example, to write compressed data

src/pkg/container/heap/heap.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package provides heap operations for any type that implements
+// Package heap provides heap operations for any type that implements
 // heap.Interface.
 //
 package heap

src/pkg/container/list/list.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The list package implements a doubly linked list.
+// Package list implements a doubly linked list.
 //
 // To iterate over a list (where l is a *List):
 //	for e := l.Front(); e != nil; e = e.Next() {

src/pkg/container/ring/ring.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The ring package implements operations on circular lists.
+// Package ring implements operations on circular lists.
 package ring
 
 // A Ring is an element of a circular list, or ring.

src/pkg/container/vector/defs.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The vector package implements containers for managing sequences
+// Package vector implements containers for managing sequences of elements.
-// of elements. Vectors grow and shrink dynamically as necessary.
+// Vectors grow and shrink dynamically as necessary.
 package vector
 
 

src/pkg/crypto/aes/const.go

@@ -2,12 +2,12 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// AES constants - 8720 bytes of initialized data.
+// Package aes implements AES encryption (formerly Rijndael), as defined in
-
+// U.S. Federal Information Processing Standards Publication 197.
-// This package implements AES encryption (formerly Rijndael),
-// as defined in U.S. Federal Information Processing Standards Publication 197.
 package aes
 
+// This file contains AES constants - 8720 bytes of initialized data.
+
 // http://www.csrc.nist.gov/publications/fips/fips197/fips-197.pdf
 
 // AES is based on the mathematical behavior of binary polynomials

src/pkg/crypto/blowfish/cipher.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements Bruce Schneier's Blowfish encryption algorithm.
+// Package blowfish implements Bruce Schneier's Blowfish encryption algorithm.
 package blowfish
 
 // The code is a port of Bruce Schneier's C implementation.

src/pkg/crypto/cast5/cast5.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements CAST5, as defined in RFC 2144. CAST5 is a common
+// Package cast5 implements CAST5, as defined in RFC 2144. CAST5 is a common
 // OpenPGP cipher.
 package cast5
 

src/pkg/crypto/cipher/cipher.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The cipher package implements standard block cipher modes
+// Package cipher implements standard block cipher modes that can be wrapped
-// that can be wrapped around low-level block cipher implementations.
+// around low-level block cipher implementations.
 // See http://csrc.nist.gov/groups/ST/toolkit/BCM/current_modes.html
 // and NIST Special Publication 800-38A.
 package cipher

src/pkg/crypto/crypto.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The crypto package collects common cryptographic constants.
+// Package crypto collects common cryptographic constants.
 package crypto
 
 import (

src/pkg/crypto/elliptic/elliptic.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The elliptic package implements several standard elliptic curves over prime
+// Package elliptic implements several standard elliptic curves over prime
-// fields
+// fields.
 package elliptic
 
 // This package operates, internally, on Jacobian coordinates. For a given

src/pkg/crypto/hmac/hmac.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The hmac package implements the Keyed-Hash Message Authentication Code (HMAC)
+// Package hmac implements the Keyed-Hash Message Authentication Code (HMAC) as
-// as defined in U.S. Federal Information Processing Standards Publication 198.
+// defined in U.S. Federal Information Processing Standards Publication 198.
 // An HMAC is a cryptographic hash that uses a key to sign a message.
 // The receiver verifies the hash by recomputing it using the same key.
 package hmac

src/pkg/crypto/md4/md4.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements the MD4 hash algorithm as defined in RFC 1320.
+// Package md4 implements the MD4 hash algorithm as defined in RFC 1320.
 package md4
 
 import (

src/pkg/crypto/md5/md5.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements the MD5 hash algorithm as defined in RFC 1321.
+// Package md5 implements the MD5 hash algorithm as defined in RFC 1321.
 package md5
 
 import (

src/pkg/crypto/ocsp/ocsp.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package parses OCSP responses as specified in RFC 2560. OCSP responses
+// Package ocsp parses OCSP responses as specified in RFC 2560. OCSP responses
 // are signed messages attesting to the validity of a certificate for a small
 // period of time. This is used to manage revocation for X.509 certificates.
 package ocsp

src/pkg/crypto/openpgp/armor/armor.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements OpenPGP ASCII Armor, see RFC 4880. OpenPGP Armor is
+// Package armor implements OpenPGP ASCII Armor, see RFC 4880. OpenPGP Armor is
 // very similar to PEM except that it has an additional CRC checksum.
 package armor
 

src/pkg/crypto/openpgp/error/error.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package contains common error types for the OpenPGP packages.
+// Package error contains common error types for the OpenPGP packages.
 package error
 
 import (

src/pkg/crypto/openpgp/packet/packet.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements parsing and serialisation of OpenPGP packets, as
+// Package packet implements parsing and serialisation of OpenPGP packets, as
 // specified in RFC 4880.
 package packet
 

src/pkg/crypto/openpgp/read.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This openpgp package implements high level operations on OpenPGP messages.
+// Package openpgp implements high level operations on OpenPGP messages.
 package openpgp
 
 import (

src/pkg/crypto/openpgp/s2k/s2k.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements the various OpenPGP string-to-key transforms as
+// Package s2k implements the various OpenPGP string-to-key transforms as
 // specified in RFC 4800 section 3.7.1.
 package s2k
 

src/pkg/crypto/rc4/rc4.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements RC4 encryption, as defined in Bruce Schneier's
+// Package rc4 implements RC4 encryption, as defined in Bruce Schneier's
 // Applied Cryptography.
 package rc4
 

src/pkg/crypto/ripemd160/ripemd160.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements the RIPEMD-160 hash algorithm.
+// Package ripemd160 implements the RIPEMD-160 hash algorithm.
 package ripemd160
 
 // RIPEMD-160 is designed by by Hans Dobbertin, Antoon Bosselaers, and Bart

src/pkg/crypto/rsa/rsa.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements RSA encryption as specified in PKCS#1.
+// Package rsa implements RSA encryption as specified in PKCS#1.
 package rsa
 
 // TODO(agl): Add support for PSS padding.

src/pkg/crypto/sha1/sha1.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements the SHA1 hash algorithm as defined in RFC 3174.
+// Package sha1 implements the SHA1 hash algorithm as defined in RFC 3174.
 package sha1
 
 import (

src/pkg/crypto/sha256/sha256.go

@@ -2,7 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements the SHA224 and SHA256 hash algorithms as defined in FIPS 180-2.
+// Package sha256 implements the SHA224 and SHA256 hash algorithms as defined
+// in FIPS 180-2.
 package sha256
 
 import (

src/pkg/crypto/sha512/sha512.go

@@ -2,7 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements the SHA384 and SHA512 hash algorithms as defined in FIPS 180-2.
+// Package sha512 implements the SHA384 and SHA512 hash algorithms as defined
+// in FIPS 180-2.
 package sha512
 
 import (

src/pkg/crypto/subtle/constant_time.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements functions that are often useful in cryptographic
+// Package subtle implements functions that are often useful in cryptographic
 // code but require careful thought to use correctly.
 package subtle
 

src/pkg/crypto/tls/tls.go

@@ -2,7 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package partially implements the TLS 1.1 protocol, as specified in RFC 4346.
+// Package tls partially implements the TLS 1.1 protocol, as specified in RFC
+// 4346.
 package tls
 
 import (

src/pkg/crypto/twofish/twofish.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements Bruce Schneier's Twofish encryption algorithm.
+// Package twofish implements Bruce Schneier's Twofish encryption algorithm.
 package twofish
 
 // Twofish is defined in http://www.schneier.com/paper-twofish-paper.pdf [TWOFISH]

src/pkg/crypto/x509/x509.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package parses X.509-encoded keys and certificates.
+// Package x509 parses X.509-encoded keys and certificates.
 package x509
 
 import (

src/pkg/crypto/xtea/cipher.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements XTEA encryption, as defined in Needham and
+// Package xtea implements XTEA encryption, as defined in Needham and Wheeler's
-// Wheeler's 1997 technical report, "Tea extensions."
+// 1997 technical report, "Tea extensions."
 package xtea
 
 // For details, see http://www.cix.co.uk/~klockstone/xtea.pdf

src/pkg/debug/dwarf/open.go

@@ -2,9 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package provides access to DWARF debugging information
+// Package dwarf provides access to DWARF debugging information loaded from
-// loaded from executable files, as defined in the DWARF 2.0 Standard
+// executable files, as defined in the DWARF 2.0 Standard at
-// at http://dwarfstd.org/doc/dwarf-2.0.0.pdf
+// http://dwarfstd.org/doc/dwarf-2.0.0.pdf
 package dwarf
 
 import (

src/pkg/ebnf/ebnf.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// A library for EBNF grammars. The input is text ([]byte) satisfying
+// Package ebnf is a library for EBNF grammars. The input is text ([]byte)
-// the following grammar (represented itself in EBNF):
+// satisfying the following grammar (represented itself in EBNF):
 //
 //	Production  = name "=" Expression "." .
 //	Expression  = Alternative { "|" Alternative } .

src/pkg/encoding/hex/hex.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements hexadecimal encoding and decoding.
+// Package hex implements hexadecimal encoding and decoding.
 package hex
 
 import (

src/pkg/encoding/line/line.go

@@ -2,7 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The line package implements a Reader that reads lines delimited by '\n' or ' \r\n'.
+// Package line implements a Reader that reads lines delimited by '\n' or
+// ' \r\n'.
 package line
 
 import (

src/pkg/encoding/pem/pem.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements the PEM data encoding, which originated in Privacy
+// Package pem implements the PEM data encoding, which originated in Privacy
 // Enhanced Mail. The most common use of PEM encoding today is in TLS keys and
 // certificates. See RFC 1421.
 package pem

src/pkg/exec/exec.go

@@ -2,9 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The exec package runs external commands. It wraps os.StartProcess
+// Package exec runs external commands. It wraps os.StartProcess to make it
-// to make it easier to remap stdin and stdout, connect I/O with pipes,
+// easier to remap stdin and stdout, connect I/O with pipes, and do other
-// and do other adjustments.
+// adjustments.
 package exec
 
 // BUG(r): This package should be made even easier to use or merged into os.

src/pkg/exp/datafmt/datafmt.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-/*	The datafmt package implements syntax-directed, type-driven formatting
+/*	Package datafmt implements syntax-directed, type-driven formatting
 	of arbitrary data structures. Formatting a data structure consists of
 	two phases: first, a parser reads a format specification and builds a
 	"compiled" format. Then, the format can be applied repeatedly to

src/pkg/exp/draw/x11/conn.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements an X11 backend for the exp/draw package.
+// Package x11 implements an X11 backend for the exp/draw package.
 //
 // The X protocol specification is at ftp://ftp.x.org/pub/X11R7.0/doc/PDF/proto.pdf.
 // A summary of the wire format can be found in XCB's xproto.xml.

src/pkg/exp/eval/world.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package is the beginning of an interpreter for Go.
+// Package eval is the beginning of an interpreter for Go.
 // It can run simple Go programs but does not implement
 // interface values or packages.
 package eval

src/pkg/exp/ogle/cmd.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Ogle is the beginning of a debugger for Go.
+// Package ogle is the beginning of a debugger for Go.
 package ogle
 
 import (

src/pkg/expvar/expvar.go

@@ -2,9 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The expvar package provides a standardized interface to public variables,
+// Package expvar provides a standardized interface to public variables, such
-// such as operation counters in servers. It exposes these variables via
+// as operation counters in servers. It exposes these variables via HTTP at
-// HTTP at /debug/vars in JSON format.
+// /debug/vars in JSON format.
 //
 // Operations to set or modify these public variables are atomic.
 //

src/pkg/flag/flag.go

@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 /*
-	The flag package implements command-line flag parsing.
+	Package flag implements command-line flag parsing.
 
 	Usage:
 

src/pkg/go/ast/ast.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The AST package declares the types used to represent
+// Package ast declares the types used to represent syntax trees for Go
-// syntax trees for Go packages.
+// packages.
 //
 package ast
 

src/pkg/go/doc/doc.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The doc package extracts source code documentation from a Go AST.
+// Package doc extracts source code documentation from a Go AST.
 package doc
 
 import (

src/pkg/go/parser/parser.go

@@ -2,10 +2,10 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// A parser for Go source files. Input may be provided in a variety of
+// Package parser implements a parser for Go source files. Input may be
-// forms (see the various Parse* functions); the output is an abstract
+// provided in a variety of forms (see the various Parse* functions); the
-// syntax tree (AST) representing the Go source. The parser is invoked
+// output is an abstract syntax tree (AST) representing the Go source. The
-// through one of the Parse* functions.
+// parser is invoked through one of the Parse* functions.
 //
 package parser
 

src/pkg/go/printer/printer.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The printer package implements printing of AST nodes.
+// Package printer implements printing of AST nodes.
 package printer
 
 import (

src/pkg/go/scanner/scanner.go

@@ -2,9 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// A scanner for Go source text. Takes a []byte as source which can
+// Package scanner implements a scanner for Go source text. Takes a []byte as
-// then be tokenized through repeated calls to the Scan function.
+// source which can then be tokenized through repeated calls to the Scan
-// Typical use:
+// function. Typical use:
 //
 //	var s Scanner
 //	fset := token.NewFileSet()  // position information is relative to fset

src/pkg/go/token/token.go

@@ -2,9 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package defines constants representing the lexical
+// Package token defines constants representing the lexical tokens of the Go
-// tokens of the Go programming language and basic operations
+// programming language and basic operations on tokens (printing, predicates).
-// on tokens (printing, predicates).
 //
 package token
 

src/pkg/go/types/types.go

@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 // PACKAGE UNDER CONSTRUCTION. ANY AND ALL PARTS MAY CHANGE.
-// The types package declares the types used to represent Go types.
+// Package types declares the types used to represent Go types.
 //
 package types
 

src/pkg/gob/doc.go

@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 /*
-The gob package manages streams of gobs - binary values exchanged between an
+Package gob manages streams of gobs - binary values exchanged between an
 Encoder (transmitter) and a Decoder (receiver).  A typical use is transporting
 arguments and results of remote procedure calls (RPCs) such as those provided by
 package "rpc".

src/pkg/hash/adler32/adler32.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements the Adler-32 checksum.
+// Package adler32 implements the Adler-32 checksum.
 // Defined in RFC 1950:
 //	Adler-32 is composed of two sums accumulated per byte: s1 is
 //	the sum of all bytes, s2 is the sum of all s1 values. Both sums

src/pkg/hash/crc32/crc32.go

@@ -2,8 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements the 32-bit cyclic redundancy check, or CRC-32, checksum.
+// Package crc32 implements the 32-bit cyclic redundancy check, or CRC-32,
-// See http://en.wikipedia.org/wiki/Cyclic_redundancy_check for information.
+// checksum. See http://en.wikipedia.org/wiki/Cyclic_redundancy_check for
+// information.
 package crc32
 
 import (

src/pkg/hash/crc64/crc64.go

@@ -2,8 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package implements the 64-bit cyclic redundancy check, or CRC-64, checksum.
+// Package crc64 implements the 64-bit cyclic redundancy check, or CRC-64,
-// See http://en.wikipedia.org/wiki/Cyclic_redundancy_check for information.
+// checksum. See http://en.wikipedia.org/wiki/Cyclic_redundancy_check for
+// information.
 package crc64
 
 import (

src/pkg/hash/fnv/fnv.go

@@ -2,9 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The fnv package implements FNV-1 and FNV-1a,
+// Package fnv implements FNV-1 and FNV-1a, non-cryptographic hash functions
-// non-cryptographic hash functions created by
+// created by Glenn Fowler, Landon Curt Noll, and Phong Vo.
-// Glenn Fowler, Landon Curt Noll, and Phong Vo.
 // See http://isthe.com/chongo/tech/comp/fnv/.
 package fnv
 

src/pkg/hash/hash.go

@@ -2,6 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Package hash provides interfaces for hash functions.
 package hash
 
 import "io"

src/pkg/html/doc.go

@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 /*
-The html package implements an HTML5-compliant tokenizer and parser.
+Package html implements an HTML5-compliant tokenizer and parser.
 
 Tokenization is done by creating a Tokenizer for an io.Reader r. It is the
 caller's responsibility to ensure that r provides UTF-8 encoded HTML.

src/pkg/http/httptest/recorder.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The httptest package provides utilities for HTTP testing.
+// Package httptest provides utilities for HTTP testing.
 package httptest
 
 import (

src/pkg/http/request.go

@@ -4,9 +4,8 @@
 
 // HTTP Request reading and parsing.
 
-// The http package implements parsing of HTTP requests, replies,
+// Package http implements parsing of HTTP requests, replies, and URLs and
-// and URLs and provides an extensible HTTP server and a basic
+// provides an extensible HTTP server and a basic HTTP client.
-// HTTP client.
 package http
 
 import (

src/pkg/image/image.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The image package implements a basic 2-D image library.
+// Package image implements a basic 2-D image library.
 package image
 
 // A Config consists of an image's color model and dimensions.

src/pkg/image/png/reader.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The png package implements a PNG image decoder and encoder.
+// Package png implements a PNG image decoder and encoder.
 //
 // The PNG specification is at http://www.libpng.org/pub/png/spec/1.2/PNG-Contents.html
 package png

src/pkg/image/ycbcr/ycbcr.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The ycbcr package provides images from the Y'CbCr color model.
+// Package ycbcr provides images from the Y'CbCr color model.
 //
 // JPEG, VP8, the MPEG family and other codecs use this color model. Such
 // codecs often use the terms YUV and Y'CbCr interchangeably, but strictly

src/pkg/index/suffixarray/suffixarray.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The suffixarray package implements substring search in logarithmic time
+// Package suffixarray implements substring search in logarithmic time using
-// using an in-memory suffix array.
+// an in-memory suffix array.
 //
 // Example use:
 //

src/pkg/io/io.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package provides basic interfaces to I/O primitives.
+// Package io provides basic interfaces to I/O primitives.
 // Its primary job is to wrap existing implementations of such primitives,
 // such as those in package os, into shared public interfaces that
 // abstract the functionality, plus some other related primitives.

src/pkg/io/ioutil/ioutil.go

@@ -2,8 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Utility functions.
+// Package ioutil implements some I/O utility functions.
-
 package ioutil
 
 import (

src/pkg/json/encode.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The json package implements encoding and decoding of JSON objects as
+// Package json implements encoding and decoding of JSON objects as defined in
-// defined in RFC 4627.
+// RFC 4627.
 package json
 
 import (

src/pkg/log/log.go

@@ -2,9 +2,9 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Simple logging package. It defines a type, Logger, with methods
+// Package log implements a simple logging package. It defines a type, Logger,
-// for formatting output. It also has a predefined 'standard' Logger
+// with methods for formatting output. It also has a predefined 'standard'
-// accessible through helper functions Print[f|ln], Fatal[f|ln], and
+// Logger accessible through helper functions Print[f|ln], Fatal[f|ln], and
 // Panic[f|ln], which are easier to use than creating a Logger manually.
 // That logger writes to standard error and prints the date and time
 // of each logged message.

src/pkg/math/const.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The math package provides basic constants and mathematical functions.
+// Package math provides basic constants and mathematical functions.
 package math
 
 // Mathematical constants.

src/pkg/mime/type.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The mime package implements parts of the MIME spec.
+// Package mime implements parts of the MIME spec.
 package mime
 
 import (

src/pkg/net/net.go

@@ -2,9 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The net package provides a portable interface to Unix
+// Package net provides a portable interface to Unix networks sockets,
-// networks sockets, including TCP/IP, UDP, domain name
+// including TCP/IP, UDP, domain name resolution, and Unix domain sockets.
-// resolution, and Unix domain sockets.
 package net
 
 // TODO(rsc):

src/pkg/net/textproto/textproto.go

@@ -2,9 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The textproto package implements generic support for
+// Package textproto implements generic support for text-based request/response
-// text-based request/response protocols in the style of
+// protocols in the style of HTTP, NNTP, and SMTP.
-// HTTP, NNTP, and SMTP.
 //
 // The package provides:
 //

src/pkg/netchan/export.go

@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 /*
-	The netchan package implements type-safe networked channels:
+	Package netchan implements type-safe networked channels:
 	it allows the two ends of a channel to appear on different
 	computers connected by a network.  It does this by transporting
 	data sent to a channel on one machine so it can be recovered

src/pkg/os/file.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The os package provides a platform-independent interface to operating
+// Package os provides a platform-independent interface to operating system
-// system functionality.  The design is Unix-like.
+// functionality.  The design is Unix-like.
 package os
 
 import (

src/pkg/os/inotify/inotify_linux.go

@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 /*
-This package implements a wrapper for the Linux inotify system.
+Package inotify implements a wrapper for the Linux inotify system.
 
 Example:
     watcher, err := inotify.NewWatcher()

src/pkg/path/filepath/path.go

@@ -2,9 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The filepath package implements utility routines for manipulating
+// Package filepath implements utility routines for manipulating filename paths
-// filename paths in a way compatible with the target operating
+// in a way compatible with the target operating system-defined file paths.
-// system-defined file paths.
 package filepath
 
 import (

src/pkg/path/path.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The path package implements utility routines for manipulating
+// Package path implements utility routines for manipulating slash-separated
-// slash-separated filename paths.
+// filename paths.
 package path
 
 import (

src/pkg/reflect/type.go

@@ -2,10 +2,10 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The reflect package implements run-time reflection, allowing a program to
+// Package reflect implements run-time reflection, allowing a program to
-// manipulate objects with arbitrary types.  The typical use is to take a
+// manipulate objects with arbitrary types.  The typical use is to take a value
-// value with static type interface{} and extract its dynamic type
+// with static type interface{} and extract its dynamic type information by
-// information by calling Typeof, which returns a Type.
+// calling Typeof, which returns a Type.
 //
 // A call to NewValue returns a Value representing the run-time data.
 // Zero takes a Type and returns a Value representing a zero value

src/pkg/rpc/server.go

@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 /*
-	The rpc package provides access to the exported methods of an object across a
+	Package rpc provides access to the exported methods of an object across a
 	network or other I/O connection.  A server registers an object, making it visible
 	as a service with the name of the type of the object.  After registration, exported
 	methods of the object will be accessible remotely.  A server may register multiple

src/pkg/runtime/debug/stack.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The debug package contains facilities for programs to debug themselves
+// Package debug contains facilities for programs to debug themselves while
-// while they are running.
+// they are running.
 package debug
 
 import (

src/pkg/runtime/extern.go

@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 /*
-	The runtime package contains operations that interact with Go's runtime system,
+	Package runtime contains operations that interact with Go's runtime system,
 	such as functions to control goroutines. It also includes the low-level type information
 	used by the reflect package; see reflect's documentation for the programmable
 	interface to the run-time type system.

src/pkg/scanner/scanner.go

@@ -2,10 +2,11 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// A scanner and tokenizer for UTF-8-encoded text.  Takes an io.Reader
+// Package scanner provides a scanner and tokenizer for UTF-8-encoded text.
-// providing the source, which then can be tokenized through repeated calls
+// It takes an io.Reader providing the source, which then can be tokenized
-// to the Scan function.  For compatibility with existing tools, the NUL
+// through repeated calls to the Scan function.  For compatibility with
-// character is not allowed (implementation restriction).
+// existing tools, the NUL character is not allowed (implementation
+// restriction).
 //
 // By default, a Scanner skips white space and Go comments and recognizes all
 // literals as defined by the Go language specification.  It may be

src/pkg/sort/sort.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The sort package provides primitives for sorting arrays
+// Package sort provides primitives for sorting arrays and user-defined
-// and user-defined collections.
+// collections.
 package sort
 
 // A type, typically a collection, that satisfies sort.Interface can be

src/pkg/strconv/atof.go

@@ -2,16 +2,16 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Package strconv implements conversions to and from string representations
+// of basic data types.
+package strconv
+
 // decimal to binary floating point conversion.
 // Algorithm:
 //   1) Store input in multiprecision decimal.
 //   2) Multiply/divide decimal by powers of two until in range [0.5, 1)
 //   3) Multiply by 2^precision and round to get mantissa.
 
-// The strconv package implements conversions to and from
-// string representations of basic data types.
-package strconv
-
 import (
 	"math"
 	"os"

src/pkg/strings/strings.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// A package of simple functions to manipulate strings.
+// Package strings implements simple functions to manipulate strings.
 package strings
 
 import (

src/pkg/sync/mutex.go

@@ -2,11 +2,10 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The sync package provides basic synchronization primitives
+// Package sync provides basic synchronization primitives such as mutual
-// such as mutual exclusion locks.  Other than the Once and
+// exclusion locks.  Other than the Once and WaitGroup types, most are intended
-// WaitGroup types, most are intended for use by low-level
+// for use by low-level library routines.  Higher-level synchronization is
-// library routines.  Higher-level synchronization is better
+// better done via channels and communication.
-// done via channels and communication.
 package sync
 
 import (

src/pkg/syscall/syscall.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// This package contains an interface to the low-level operating system
+// Package syscall contains an interface to the low-level operating system
 // primitives.  The details vary depending on the underlying system.
 // Its primary use is inside other packages that provide a more portable
 // interface to the system, such as "os", "time" and "net".  Use those

src/pkg/syslog/syslog.go

@@ -2,9 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The syslog package provides a simple interface to
+// Package syslog provides a simple interface to the system log service. It
-// the system log service. It can send messages to the
+// can send messages to the syslog daemon using UNIX domain sockets, UDP, or
-// syslog daemon using UNIX domain sockets, UDP, or
 // TCP connections.
 package syslog
 

src/pkg/tabwriter/tabwriter.go

@@ -2,8 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// The tabwriter package implements a write filter (tabwriter.Writer)
+// Package tabwriter implements a write filter (tabwriter.Writer) that
-// that translates tabbed columns in input into properly aligned text.
+// translates tabbed columns in input into properly aligned text.
 //
 // The package is using the Elastic Tabstops algorithm described at
 // http://nickgravgaard.com/elastictabstops/index.html.

src/pkg/template/template.go

@@ -3,8 +3,8 @@
 // license that can be found in the LICENSE file.
 
 /*
-	Data-driven templates for generating textual output such as
+	Package template implements data-driven templates for generating textual
-	HTML.
+	output such as HTML.
 
 	Templates are executed by applying them to a data structure.
 	Annotations in the template refer to elements of the data