From 546196a6fa8174d68f5c92071ff4bc6edd1ce3d0 Mon Sep 17 00:00:00 2001
From: Raul Jordan <raul@prysmaticlabs.com>
Date: Wed, 29 Apr 2020 16:32:39 -0500
Subject: [PATCH] Other Package Godocs for Prysm (#5681)

* e2e docs
* slasher docs
* Merge branch 'other-package-godocs' of github.com:prysmaticlabs/prysm into other-package-godocs
* all validator package comments
* Merge branch 'master' into other-package-godocs
* completed all other packages
* Merge branch 'master' into other-package-godocs
* Merge refs/heads/master into other-package-godocs
---
 endtoend/README.md                            | 2 +-
 endtoend/components/beacon_node.go            | 2 ++
 endtoend/endtoend_test.go                     | 4 ++++
 endtoend/evaluators/node.go                   | 2 ++
 endtoend/helpers/helpers.go                   | 2 ++
 endtoend/params/params.go                     | 2 ++
 endtoend/types/types.go                       | 2 ++
 shared/attestationutil/attestation_utils.go   | 2 ++
 shared/benchutil/pregen.go                    | 2 ++
 shared/bls/spectest/sign_test.go              | 2 ++
 shared/event/feed.go                          | 1 +
 shared/hashutil/hash.go                       | 1 +
 shared/interop/generate_genesis_state.go      | 2 ++
 shared/iputils/external_ip.go                 | 1 +
 shared/keystore/deposit_input.go              | 2 ++
 shared/mathutil/math_helper.go                | 1 +
 shared/mclockutil/mclock.go                   | 2 +-
 shared/memorypool/memorypool.go               | 2 ++
 shared/messagehandler/messagehandler.go       | 2 ++
 shared/mputil/scatter.go                      | 2 ++
 shared/p2putils/fork.go                       | 1 +
 shared/pagination/pagination.go               | 1 +
 shared/params/config.go                       | 3 +--
 shared/params/spectest/config.go              | 2 ++
 shared/prometheus/service.go                  | 2 ++
 shared/roughtime/roughtime.go                 | 2 +-
 shared/runutil/every.go                       | 1 +
 shared/service_registry.go                    | 2 ++
 shared/slotutil/slotticker.go                 | 1 +
 shared/slotutil/testing/mock.go               | 1 +
 shared/testutil/log.go                        | 2 +-
 shared/traceutil/errors.go                    | 1 +
 shared/tracing/tracer.go                      | 2 ++
 shared/trieutil/sparse_merkle.go              | 1 +
 shared/version/version.go                     | 2 ++
 slasher/cache/span_cache.go                   | 3 +++
 slasher/db/db.go                              | 1 +
 slasher/db/iface/interface.go                 | 3 +++
 slasher/db/kv/kv.go                           | 2 ++
 slasher/db/testing/setup_db.go                | 2 ++
 slasher/db/types/types.go                     | 2 ++
 slasher/detection/attestations/iface/iface.go | 1 +
 slasher/detection/attestations/spanner.go     | 2 ++
 slasher/detection/attestations/types/types.go | 2 ++
 slasher/detection/proposals/detector.go       | 2 ++
 slasher/detection/proposals/iface/iface.go    | 1 +
 slasher/detection/testing/utils.go            | 2 ++
 slasher/flags/flags.go                        | 2 ++
 slasher/main.go                               | 3 +++
 slasher/node/node.go                          | 3 +++
 slasher/rpc/service.go                        | 3 +++
 validator/accounts/account.go                 | 1 +
 validator/client/service.go                   | 2 ++
 validator/db/db.go                            | 1 +
 validator/db/iface/interface.go               | 2 +-
 validator/flags/flags.go                      | 2 ++
 validator/main.go                             | 3 +++
 validator/node/node.go                        | 5 +++--
 58 files changed, 103 insertions(+), 9 deletions(-)

diff --git a/endtoend/README.md b/endtoend/README.md
index 75a9f77810e8..9fb7ee444af8 100644
--- a/endtoend/README.md
+++ b/endtoend/README.md
@@ -1,6 +1,6 @@
 # End-to-end Testing Package
 
-This is the main project folder of the end-to-end testing suite for Prysm. This performs a full end-to-end test for Prysm, including spinning up an ETH1 dev chain, sending deposits to the deposit contract, and making sure the beacon node and it's validators are running and performing properly for a few epochs.
+This is the main project folder of the end-to-end testing suite for Prysm. This performs a full end-to-end test for Prysm, including spinning up an ETH1 dev chain, sending deposits to the deposit contract, and making sure the beacon node and its validators are running and performing properly for a few epochs.
 It also performs a test on a syncing node, and supports featureflags to allow easy E2E testing of experimental features. 
 
 ## How it works
diff --git a/endtoend/components/beacon_node.go b/endtoend/components/beacon_node.go
index d1bf8678a636..95826c4bd13a 100644
--- a/endtoend/components/beacon_node.go
+++ b/endtoend/components/beacon_node.go
@@ -1,3 +1,5 @@
+// Package components defines utilities to spin up actual
+// beacon node and validator processes as needed by end to end tests.
 package components
 
 import (
diff --git a/endtoend/endtoend_test.go b/endtoend/endtoend_test.go
index c32b0d443dca..2684f5fa14db 100644
--- a/endtoend/endtoend_test.go
+++ b/endtoend/endtoend_test.go
@@ -1,3 +1,7 @@
+// Package endtoend performs full a end-to-end test for Prysm,
+// including spinning up an ETH1 dev chain, sending deposits to the deposit
+// contract, and making sure the beacon node and validators are running and
+// performing properly for a few epochs.
 package endtoend
 
 import (
diff --git a/endtoend/evaluators/node.go b/endtoend/evaluators/node.go
index f5cceeff35c9..af6495d0f0b2 100644
--- a/endtoend/evaluators/node.go
+++ b/endtoend/evaluators/node.go
@@ -1,3 +1,5 @@
+// Package evaluators defines functions which can peer into end to end
+// tests to determine if a chain is running as required.
 package evaluators
 
 import (
diff --git a/endtoend/helpers/helpers.go b/endtoend/helpers/helpers.go
index 9560eaef1c43..ea57e6f622f8 100644
--- a/endtoend/helpers/helpers.go
+++ b/endtoend/helpers/helpers.go
@@ -1,3 +1,5 @@
+// Package helpers defines helper functions to peer into
+// end to end processes and kill processes as needed.
 package helpers
 
 import (
diff --git a/endtoend/params/params.go b/endtoend/params/params.go
index a1bb3c8ac8d8..cbb2df358da7 100644
--- a/endtoend/params/params.go
+++ b/endtoend/params/params.go
@@ -1,3 +1,5 @@
+// Package params defines all custom parameter configurations
+// for running end to end tests.
 package params
 
 import (
diff --git a/endtoend/types/types.go b/endtoend/types/types.go
index 9256eb7b6115..aa1ce774fc9b 100644
--- a/endtoend/types/types.go
+++ b/endtoend/types/types.go
@@ -1,3 +1,5 @@
+// Package types includes important structs used by end to end tests, such
+// as a configuration type, an evaluator type, and more.
 package types
 
 import (
diff --git a/shared/attestationutil/attestation_utils.go b/shared/attestationutil/attestation_utils.go
index 467af0fd6b24..7b5b2bc417a2 100644
--- a/shared/attestationutil/attestation_utils.go
+++ b/shared/attestationutil/attestation_utils.go
@@ -1,3 +1,5 @@
+// Package attestationutil contains useful helpers for converting
+// attestations into indexed form.
 package attestationutil
 
 import (
diff --git a/shared/benchutil/pregen.go b/shared/benchutil/pregen.go
index 3e9e43a69e5b..0522a65c39b6 100644
--- a/shared/benchutil/pregen.go
+++ b/shared/benchutil/pregen.go
@@ -1,3 +1,5 @@
+// Package benchutil contains useful helpers
+// for pregenerating filled data structures such as blocks/states for benchmarks.
 package benchutil
 
 import (
diff --git a/shared/bls/spectest/sign_test.go b/shared/bls/spectest/sign_test.go
index 9c81c2aefccc..4c66f73bde91 100644
--- a/shared/bls/spectest/sign_test.go
+++ b/shared/bls/spectest/sign_test.go
@@ -1,3 +1,5 @@
+// Package spectest includes tests to ensure conformity with the eth2
+// bls cryptography specification.
 package spectest
 
 import (
diff --git a/shared/event/feed.go b/shared/event/feed.go
index 02f3ca68759f..8e3643f0b01a 100644
--- a/shared/event/feed.go
+++ b/shared/event/feed.go
@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
 
+// Package event contains an event feed implementation for process communication.
 package event
 
 import (
diff --git a/shared/hashutil/hash.go b/shared/hashutil/hash.go
index d88ca533e751..a5825df5c142 100644
--- a/shared/hashutil/hash.go
+++ b/shared/hashutil/hash.go
@@ -1,3 +1,4 @@
+// Package hashutil includes all hash-function related helpers for Prysm.
 package hashutil
 
 import (
diff --git a/shared/interop/generate_genesis_state.go b/shared/interop/generate_genesis_state.go
index 7a90c85dc541..6a015e01392b 100644
--- a/shared/interop/generate_genesis_state.go
+++ b/shared/interop/generate_genesis_state.go
@@ -1,3 +1,5 @@
+// Package interop contains deterministic utilities for generating
+// genesis states and keys.
 package interop
 
 import (
diff --git a/shared/iputils/external_ip.go b/shared/iputils/external_ip.go
index 02e5e515095e..a0cee5104b1b 100644
--- a/shared/iputils/external_ip.go
+++ b/shared/iputils/external_ip.go
@@ -1,3 +1,4 @@
+// Package iputils contains useful functions for ip address formatting.
 package iputils
 
 import (
diff --git a/shared/keystore/deposit_input.go b/shared/keystore/deposit_input.go
index 25ab7e965ec3..5daad60e589a 100644
--- a/shared/keystore/deposit_input.go
+++ b/shared/keystore/deposit_input.go
@@ -1,3 +1,5 @@
+// Package keystore contains useful functions for dealing
+// with eth2 deposit inputs leveraging go-ethereum's own keystore package.
 package keystore
 
 import (
diff --git a/shared/mathutil/math_helper.go b/shared/mathutil/math_helper.go
index c3c603197528..c54d779f6505 100644
--- a/shared/mathutil/math_helper.go
+++ b/shared/mathutil/math_helper.go
@@ -1,3 +1,4 @@
+// Package mathutil includes important helpers for eth2 such as fast integer square roots.
 package mathutil
 
 import (
diff --git a/shared/mclockutil/mclock.go b/shared/mclockutil/mclock.go
index a1d844f3cd43..af817f932321 100644
--- a/shared/mclockutil/mclock.go
+++ b/shared/mclockutil/mclock.go
@@ -14,7 +14,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
 
-// Package mclockutil is a wrapper for a monotonic clock source
+// Package mclockutil is a wrapper for a monotonic clock source.
 package mclockutil
 
 import (
diff --git a/shared/memorypool/memorypool.go b/shared/memorypool/memorypool.go
index 76cda73b7ca7..5539c36787e9 100644
--- a/shared/memorypool/memorypool.go
+++ b/shared/memorypool/memorypool.go
@@ -1,3 +1,5 @@
+// Package memorypool includes useful tools for creating common
+// data structures in eth2 with optimal memory allocation.
 package memorypool
 
 import (
diff --git a/shared/messagehandler/messagehandler.go b/shared/messagehandler/messagehandler.go
index 9b2a264649fc..9d5d7ccfeae9 100644
--- a/shared/messagehandler/messagehandler.go
+++ b/shared/messagehandler/messagehandler.go
@@ -1,3 +1,5 @@
+// Package messagehandler contains useful helpers for recovering
+// from panic conditions at runtime and logging their trace.
 package messagehandler
 
 import (
diff --git a/shared/mputil/scatter.go b/shared/mputil/scatter.go
index 993c7ceb996c..ceb1fba585b4 100644
--- a/shared/mputil/scatter.go
+++ b/shared/mputil/scatter.go
@@ -1,3 +1,5 @@
+// Package mputil contains useful helpers for converting
+// multi-processor computation.
 package mputil
 
 import (
diff --git a/shared/p2putils/fork.go b/shared/p2putils/fork.go
index 52b2681582c6..d7fb2d585d74 100644
--- a/shared/p2putils/fork.go
+++ b/shared/p2putils/fork.go
@@ -1,3 +1,4 @@
+// Package p2putils contains useful helpers for eth2 fork-related functionality.
 package p2putils
 
 import (
diff --git a/shared/pagination/pagination.go b/shared/pagination/pagination.go
index 885d94dfb1f1..4130be83910a 100644
--- a/shared/pagination/pagination.go
+++ b/shared/pagination/pagination.go
@@ -1,3 +1,4 @@
+// Package pagination contains useful pagination-related helpers.
 package pagination
 
 import (
diff --git a/shared/params/config.go b/shared/params/config.go
index 9ed2fe16ecc9..b5a5c650ce97 100644
--- a/shared/params/config.go
+++ b/shared/params/config.go
@@ -1,5 +1,4 @@
-// Package params defines important constants that are essential to the
-// Ethereum 2.0 services.
+// Package params defines important constants that are essential to eth2 services.
 package params
 
 import (
diff --git a/shared/params/spectest/config.go b/shared/params/spectest/config.go
index e808722fbcfb..0082d00d55f3 100644
--- a/shared/params/spectest/config.go
+++ b/shared/params/spectest/config.go
@@ -1,3 +1,5 @@
+// Package spectest allows for easy switching of chain
+// configuration parameters in spec conformity unit tests.
 package spectest
 
 import (
diff --git a/shared/prometheus/service.go b/shared/prometheus/service.go
index 71e139bc9450..b7041f86acb4 100644
--- a/shared/prometheus/service.go
+++ b/shared/prometheus/service.go
@@ -1,3 +1,5 @@
+// Package prometheus defines a service which is used for metrics collection
+// and health of a node in Prysm.
 package prometheus
 
 import (
diff --git a/shared/roughtime/roughtime.go b/shared/roughtime/roughtime.go
index 8e258f1b0e2d..f099e3d4a96b 100644
--- a/shared/roughtime/roughtime.go
+++ b/shared/roughtime/roughtime.go
@@ -1,4 +1,4 @@
-// Package roughtime is a wrapper for a roughtime clock source
+// Package roughtime is a wrapper for a roughtime clock source.
 package roughtime
 
 import (
diff --git a/shared/runutil/every.go b/shared/runutil/every.go
index ac938bda2d96..c58a20f482b1 100644
--- a/shared/runutil/every.go
+++ b/shared/runutil/every.go
@@ -1,3 +1,4 @@
+// Package runutil includes helpers for scheduling runnable, periodic functions.
 package runutil
 
 import (
diff --git a/shared/service_registry.go b/shared/service_registry.go
index ebe5edc28adb..24f9e5ec078f 100644
--- a/shared/service_registry.go
+++ b/shared/service_registry.go
@@ -1,3 +1,5 @@
+// Package shared includes useful utilities globally accessible in
+// the Prysm monorepo.
 package shared
 
 import (
diff --git a/shared/slotutil/slotticker.go b/shared/slotutil/slotticker.go
index 70d7427e83d8..ec20a6213877 100644
--- a/shared/slotutil/slotticker.go
+++ b/shared/slotutil/slotticker.go
@@ -1,3 +1,4 @@
+// Package slotutil includes ticker and timer-related functions for eth2.
 package slotutil
 
 import (
diff --git a/shared/slotutil/testing/mock.go b/shared/slotutil/testing/mock.go
index 76669e59063a..3919b3009398 100644
--- a/shared/slotutil/testing/mock.go
+++ b/shared/slotutil/testing/mock.go
@@ -1,3 +1,4 @@
+// Package testing includes useful mocks for slot tickers in unit tests.
 package testing
 
 // MockTicker defines a useful struct for mocking the Ticker interface
diff --git a/shared/testutil/log.go b/shared/testutil/log.go
index c995d10736df..507bb8f6d75a 100644
--- a/shared/testutil/log.go
+++ b/shared/testutil/log.go
@@ -1,4 +1,4 @@
-// Package testutil defines the testing utils such as asserting logs.
+// Package testutil defines common unit test utils such as asserting logs.
 package testutil
 
 import (
diff --git a/shared/traceutil/errors.go b/shared/traceutil/errors.go
index 85f7a9ecc366..2af4448315a0 100644
--- a/shared/traceutil/errors.go
+++ b/shared/traceutil/errors.go
@@ -1,3 +1,4 @@
+// Package traceutil includes useful functions for opentracing annotations.
 package traceutil
 
 import (
diff --git a/shared/tracing/tracer.go b/shared/tracing/tracer.go
index 0c87e1fd8e63..11526568aa58 100644
--- a/shared/tracing/tracer.go
+++ b/shared/tracing/tracer.go
@@ -1,3 +1,5 @@
+// Package tracing sets up jaeger as an opentracing tool
+// for services in Prysm.
 package tracing
 
 import (
diff --git a/shared/trieutil/sparse_merkle.go b/shared/trieutil/sparse_merkle.go
index aa2b4303f366..4477064f35e5 100644
--- a/shared/trieutil/sparse_merkle.go
+++ b/shared/trieutil/sparse_merkle.go
@@ -1,3 +1,4 @@
+// Package trieutil defines utilities for sparse merkle tries for eth2.
 package trieutil
 
 import (
diff --git a/shared/version/version.go b/shared/version/version.go
index 5516c91fdd95..68815ce22f93 100644
--- a/shared/version/version.go
+++ b/shared/version/version.go
@@ -1,3 +1,5 @@
+// Package version executes and returns the version string
+// for the currently running process.
 package version
 
 import (
diff --git a/slasher/cache/span_cache.go b/slasher/cache/span_cache.go
index 1202ef8353b3..613270fc3c70 100644
--- a/slasher/cache/span_cache.go
+++ b/slasher/cache/span_cache.go
@@ -1,3 +1,6 @@
+// Package cache contains critical caches necessary for the runtime
+// of the slasher service, being able to keep attestation spans by epoch
+// for the validators active in the beacon chain.
 package cache
 
 import (
diff --git a/slasher/db/db.go b/slasher/db/db.go
index 9299728a6a67..8f7e7dd1d497 100644
--- a/slasher/db/db.go
+++ b/slasher/db/db.go
@@ -1,3 +1,4 @@
+// Package db defines a persistent backend for the slasher service.
 package db
 
 import (
diff --git a/slasher/db/iface/interface.go b/slasher/db/iface/interface.go
index 3c03919bbe47..925f3584b61f 100644
--- a/slasher/db/iface/interface.go
+++ b/slasher/db/iface/interface.go
@@ -1,3 +1,6 @@
+// Package iface defines an interface for the slasher database,
+// providing more advanced interfaces such as a
+// ReadOnlyDatabase.
 package iface
 
 import (
diff --git a/slasher/db/kv/kv.go b/slasher/db/kv/kv.go
index 2a5647e96a9d..95ab243d0e3b 100644
--- a/slasher/db/kv/kv.go
+++ b/slasher/db/kv/kv.go
@@ -1,3 +1,5 @@
+// Package kv defines a bolt-db, key-value store implementation of
+// the slasher database interface.
 package kv
 
 import (
diff --git a/slasher/db/testing/setup_db.go b/slasher/db/testing/setup_db.go
index 121a6d6ea897..62dbf8cc1fe4 100644
--- a/slasher/db/testing/setup_db.go
+++ b/slasher/db/testing/setup_db.go
@@ -1,3 +1,5 @@
+// Package testing defines useful helper functions for unit tests with
+// the slasher database.
 package testing
 
 import (
diff --git a/slasher/db/types/types.go b/slasher/db/types/types.go
index 002a36b9aef7..da694d8ca957 100644
--- a/slasher/db/types/types.go
+++ b/slasher/db/types/types.go
@@ -1,3 +1,5 @@
+// Package types includes important database-related types for
+// slasher-specific logic.
 package types
 
 // SlashingStatus enum like structure.
diff --git a/slasher/detection/attestations/iface/iface.go b/slasher/detection/attestations/iface/iface.go
index effb32b6972a..d2993ace3455 100644
--- a/slasher/detection/attestations/iface/iface.go
+++ b/slasher/detection/attestations/iface/iface.go
@@ -1,3 +1,4 @@
+// Package iface defines an interface for a slashable attestation detector struct.
 package iface
 
 import (
diff --git a/slasher/detection/attestations/spanner.go b/slasher/detection/attestations/spanner.go
index 9d2833c1a513..2d0223f2d624 100644
--- a/slasher/detection/attestations/spanner.go
+++ b/slasher/detection/attestations/spanner.go
@@ -1,3 +1,5 @@
+// Package attestations defines an implementation of a
+// slashable attestation detector using min-max surround vote checking.
 package attestations
 
 import (
diff --git a/slasher/detection/attestations/types/types.go b/slasher/detection/attestations/types/types.go
index 7c82b9a1b10c..962d5e5ccc79 100644
--- a/slasher/detection/attestations/types/types.go
+++ b/slasher/detection/attestations/types/types.go
@@ -1,3 +1,5 @@
+// Package types includes important type definitions for
+// slashable objects detected by slasher.
 package types
 
 import "github.com/prysmaticlabs/prysm/shared/bytesutil"
diff --git a/slasher/detection/proposals/detector.go b/slasher/detection/proposals/detector.go
index 5253006d5959..7a6820089671 100644
--- a/slasher/detection/proposals/detector.go
+++ b/slasher/detection/proposals/detector.go
@@ -1,3 +1,5 @@
+// Package proposals defines an implementation of a double-propose
+// detector in the slasher runtime.
 package proposals
 
 import (
diff --git a/slasher/detection/proposals/iface/iface.go b/slasher/detection/proposals/iface/iface.go
index 6dd324a8b471..af98bd4d3295 100644
--- a/slasher/detection/proposals/iface/iface.go
+++ b/slasher/detection/proposals/iface/iface.go
@@ -1,3 +1,4 @@
+// Package iface defines an interface for a double-proposal detector struct.
 package iface
 
 import (
diff --git a/slasher/detection/testing/utils.go b/slasher/detection/testing/utils.go
index 843f7b121c0b..b8e0173622ba 100644
--- a/slasher/detection/testing/utils.go
+++ b/slasher/detection/testing/utils.go
@@ -1,3 +1,5 @@
+// Package testing includes useful helpers for slasher-related
+// unit tests.
 package testing
 
 import (
diff --git a/slasher/flags/flags.go b/slasher/flags/flags.go
index 7231f4b498c2..2a24681dfd77 100644
--- a/slasher/flags/flags.go
+++ b/slasher/flags/flags.go
@@ -1,3 +1,5 @@
+// Package flags contains all configuration runtime flags for
+// the slasher service.
 package flags
 
 import (
diff --git a/slasher/main.go b/slasher/main.go
index 8baed4c7e878..7dbde75047f1 100644
--- a/slasher/main.go
+++ b/slasher/main.go
@@ -1,3 +1,6 @@
+// Package main defines slasher server implementation for eth2. A slasher
+// listens for all broadcasted messages using a running beacon node in order
+// to detect malicious attestations and block proposals.
 package main
 
 import (
diff --git a/slasher/node/node.go b/slasher/node/node.go
index 4be359e3f9a8..d66192e0c6ee 100644
--- a/slasher/node/node.go
+++ b/slasher/node/node.go
@@ -1,3 +1,6 @@
+// Package node is the main process which handles the lifecycle of
+// the runtime services in a slasher process, gracefully shutting
+// everything down upon close.
 package node
 
 import (
diff --git a/slasher/rpc/service.go b/slasher/rpc/service.go
index 2d4e3edb2c79..1f8f90afffdb 100644
--- a/slasher/rpc/service.go
+++ b/slasher/rpc/service.go
@@ -1,3 +1,6 @@
+// Package rpc defines an implementation of a gRPC slasher service,
+// providing endpoints for determining whether or not a block/attestation
+// is slashable based on slasher's evidence.
 package rpc
 
 import (
diff --git a/validator/accounts/account.go b/validator/accounts/account.go
index e562bee53e9f..15315280d550 100644
--- a/validator/accounts/account.go
+++ b/validator/accounts/account.go
@@ -1,3 +1,4 @@
+// Package accounts defines tools to manage an encrypted validator keystore.
 package accounts
 
 import (
diff --git a/validator/client/service.go b/validator/client/service.go
index 50d7b75d930f..82a614515b80 100644
--- a/validator/client/service.go
+++ b/validator/client/service.go
@@ -1,3 +1,5 @@
+// Package client defines the entire lifecycle of a validator in eth2 – it is responsible
+// for interacting with a beacon node to determine and perform validator duties.
 package client
 
 import (
diff --git a/validator/db/db.go b/validator/db/db.go
index e043d9cac8b9..1b0513b3faea 100644
--- a/validator/db/db.go
+++ b/validator/db/db.go
@@ -1,3 +1,4 @@
+// Package db defines a persistent backend for the validator service.
 package db
 
 import (
diff --git a/validator/db/iface/interface.go b/validator/db/iface/interface.go
index 0b4d1b3af051..75633bdadf5a 100644
--- a/validator/db/iface/interface.go
+++ b/validator/db/iface/interface.go
@@ -1,4 +1,4 @@
-// Package iface exists to prevent circular dependencies when implementing the database interface.
+// Package iface defines an interface for the validator database.
 package iface
 
 import (
diff --git a/validator/flags/flags.go b/validator/flags/flags.go
index 469cb60b732d..7117542ce9c3 100644
--- a/validator/flags/flags.go
+++ b/validator/flags/flags.go
@@ -1,3 +1,5 @@
+// Package flags contains all configuration runtime flags for
+// the validator service.
 package flags
 
 import (
diff --git a/validator/main.go b/validator/main.go
index ef4148e8bca7..ec65002501f9 100644
--- a/validator/main.go
+++ b/validator/main.go
@@ -1,3 +1,6 @@
+// Package main defines a validator client, a critical actor in eth2 which manages
+// a keystore of private keys, connects to a beacon node to receive assignments,
+// and submits blocks/attestations as needed.
 package main
 
 import (
diff --git a/validator/node/node.go b/validator/node/node.go
index e9a3b07e19ea..1ead8b426f1d 100644
--- a/validator/node/node.go
+++ b/validator/node/node.go
@@ -1,5 +1,6 @@
-// Package node defines a validator client which connects to a
-// full beacon node as part of the Ethereum Serenity specification.
+// Package node is the main process which handles the lifecycle of
+// the runtime services in a validator client process, gracefully shutting
+// everything down upon close.
 package node
 
 import (