all: add some godoc synopsis comments

accounts/account_manager.go

@@ -14,18 +14,14 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
-/*
-
-This abstracts part of a user's interaction with an account she controls.
-It's not an abstraction of core Ethereum accounts data type / logic -
-for that see the core processing code of blocks / txs.
-
-Currently this is pretty much a passthrough to the KeyStore interface,
-and accounts persistence is derived from stored keys' addresses
-
-*/
+// Package implements a private key management facility.
+//
+// This abstracts part of a user's interaction with an account she controls.
 package accounts
 
+// Currently this is pretty much a passthrough to the KeyStore interface,
+// and accounts persistence is derived from stored keys' addresses
+
 import (
 	"crypto/ecdsa"
 	crand "crypto/rand"

build/update-license.go

@@ -16,6 +16,7 @@ address for each author. See git-shortlog(1) for an explanation of the
 Please review the resulting diff to check whether the correct
 copyright assignments are performed.
 */
+
 package main
 
 import (

cmd/bootnode/main.go

@@ -14,7 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
-// Command bootnode runs a bootstrap node for the Discovery Protocol.
+// bootnode runs a bootstrap node for the Ethereum Discovery Protocol.
 package main
 
 import (

cmd/disasm/main.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// disasm is a pretty-printer for EVM bytecode.
 package main
 
 import (

cmd/ethtest/main.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// ethtest executes Ethereum JSON tests.
 package main
 
 import (

cmd/evm/main.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// evm executes EVM code snippets.
 package main
 
 import (

cmd/geth/main.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// geth is the official command-line client for Ethereum.
 package main
 
 import (

cmd/utils/cmd.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package utils contains internal helper functions for go-ethereum commands.
 package utils
 
 import (

common/bytes.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package common contains various helper functions.
 package common
 
 import (

compression/rle/read_write.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package rle implements the run-length encoding used for Ethereum data.
 package rle
 
 import (

core/chain_manager.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package core implements the Ethereum consensus protocol.
 package core
 
 import (

core/state/statedb.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package state provides a caching layer atop the Ethereum state trie.
 package state
 
 import (

core/types/block.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package types contains data types related to Ethereum consensus.
 package types
 
 import (

core/vm/vm.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package vm implements the Ethereum Virtual Machine.
 package vm
 
 import (

eth/backend.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package eth implements the Ethereum protocol.
 package eth
 
 import (

event/filter/filter.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package filter implements event filters.
 package filter
 
 import "reflect"

jsre/jsre.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package jsre provides execution environment for JavaScript.
 package jsre
 
 import (

miner/miner.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package miner implements Ethereum block creation and mining.
 package miner
 
 import (

p2p/nat/nat.go

@@ -14,7 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
-// Package nat provides access to common port mapping protocols.
+// Package nat provides access to common network port mapping protocols.
 package nat
 
 import (

p2p/server.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package p2p implements the Ethereum p2p network protocols.
 package p2p
 
 import (

rpc/xeth.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package rpc implements the Ethereum JSON-RPC API.
 package rpc
 
 import (

tests/init.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package tests implements execution of Ethereum JSON tests.
 package tests
 
 import (

trie/trie.go

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
+// Package trie implements Merkle Patricia Tries.
 package trie
 
 import (

xeth/xeth.go

@@ -14,7 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with go-ethereum.  If not, see <http://www.gnu.org/licenses/>.
 
-// eXtended ETHereum
+// Package xeth is the interface to all Ethereum functionality.
 package xeth
 
 import (