all: add some godoc synopsis comments

24 files changed, 29 insertions, 13 deletions

diff --git a/accounts/account_manager.go b/accounts/account_manager.go
index 8262faf21..c9e06261a 100644
--- a/accounts/account_manager.go
+++ b/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"
diff --git a/build/update-license.go b/build/update-license.go
index ad7aad394..abb17f872 100644
--- a/build/update-license.go
+++ b/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 (
diff --git a/cmd/bootnode/main.go b/cmd/bootnode/main.go
index 6f0ae4bd5..397fa099c 100644
--- a/cmd/bootnode/main.go
+++ b/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 (
diff --git a/cmd/disasm/main.go b/cmd/disasm/main.go
index 93c85b8bb..4bcd8608a 100644
--- a/cmd/disasm/main.go
+++ b/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 (
diff --git a/cmd/ethtest/main.go b/cmd/ethtest/main.go
index b2acd84c7..61276b177 100644
--- a/cmd/ethtest/main.go
+++ b/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 (
diff --git a/cmd/evm/main.go b/cmd/evm/main.go
index 9c1bd4b72..6420c83be 100644
--- a/cmd/evm/main.go
+++ b/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 (
diff --git a/cmd/geth/main.go b/cmd/geth/main.go
index 251121030..bb6ddc1e2 100644
--- a/cmd/geth/main.go
+++ b/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 (
diff --git a/cmd/utils/cmd.go b/cmd/utils/cmd.go
index 9d95732c0..2949d2470 100644
--- a/cmd/utils/cmd.go
+++ b/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 (
diff --git a/common/bytes.go b/common/bytes.go
index 564cfe339..a65c0122b 100644
--- a/common/bytes.go
+++ b/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 (
diff --git a/compression/rle/read_write.go b/compression/rle/read_write.go
index 2903cd101..be5d1fbcc 100644
--- a/compression/rle/read_write.go
+++ b/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 (
diff --git a/core/chain_manager.go b/core/chain_manager.go
index d8123c14e..bd49bafc2 100644
--- a/core/chain_manager.go
+++ b/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 (
diff --git a/core/state/statedb.go b/core/state/statedb.go
index 7271373dd..3a2ad10e2 100644
--- a/core/state/statedb.go
+++ b/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 (
diff --git a/core/types/block.go b/core/types/block.go
index 45bab2c95..562fa64b9 100644
--- a/core/types/block.go
+++ b/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 (
diff --git a/core/vm/vm.go b/core/vm/vm.go
index 3fca5f636..9b3fd0009 100644
--- a/core/vm/vm.go
+++ b/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 (
diff --git a/eth/backend.go b/eth/backend.go
index ede8af88f..391a610e3 100644
--- a/eth/backend.go
+++ b/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 (
diff --git a/event/filter/filter.go b/event/filter/filter.go
index 1cdd6819d..90bc4bd46 100644
--- a/event/filter/filter.go
+++ b/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"
diff --git a/jsre/jsre.go b/jsre/jsre.go
index b226b7aaa..c05af29a3 100644
--- a/jsre/jsre.go
+++ b/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 (
diff --git a/miner/miner.go b/miner/miner.go
index 4d44b8c74..173be1a14 100644
--- a/miner/miner.go
+++ b/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 (
diff --git a/p2p/nat/nat.go b/p2p/nat/nat.go
index e7f13ad48..1d4140aa0 100644
--- a/p2p/nat/nat.go
+++ b/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 (
diff --git a/p2p/server.go b/p2p/server.go
index 870eb5590..33de4f32a 100644
--- a/p2p/server.go
+++ b/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 (
diff --git a/rpc/xeth.go b/rpc/xeth.go
index e7982b15b..607f45274 100644
--- a/rpc/xeth.go
+++ b/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 (
diff --git a/tests/init.go b/tests/init.go
index 7ccf2098d..94178af5f 100644
--- a/tests/init.go
+++ b/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 (
diff --git a/trie/trie.go b/trie/trie.go
index 8028cc5f8..30c2569fa 100644
--- a/trie/trie.go
+++ b/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 (
diff --git a/xeth/xeth.go b/xeth/xeth.go
index 75ff8539a..d1085dc92 100644
--- a/xeth/xeth.go
+++ b/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 (