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

@@ -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

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 (

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 (

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 (

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 (

endtoend/params/params.go

@@ -1,3 +1,5 @@
+// Package params defines all custom parameter configurations
+// for running end to end tests.
 package params
 
 import (

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 (

shared/attestationutil/attestation_utils.go

@@ -1,3 +1,5 @@
+// Package attestationutil contains useful helpers for converting
+// attestations into indexed form.
 package attestationutil
 
 import (

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 (

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 (

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 (

shared/hashutil/hash.go

@@ -1,3 +1,4 @@
+// Package hashutil includes all hash-function related helpers for Prysm.
 package hashutil
 
 import (

shared/interop/generate_genesis_state.go

@@ -1,3 +1,5 @@
+// Package interop contains deterministic utilities for generating
+// genesis states and keys.
 package interop
 
 import (

shared/iputils/external_ip.go

@@ -1,3 +1,4 @@
+// Package iputils contains useful functions for ip address formatting.
 package iputils
 
 import (

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 (

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 (

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 (

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 (

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 (

shared/mputil/scatter.go

@@ -1,3 +1,5 @@
+// Package mputil contains useful helpers for converting
+// multi-processor computation.
 package mputil
 
 import (

shared/p2putils/fork.go

@@ -1,3 +1,4 @@
+// Package p2putils contains useful helpers for eth2 fork-related functionality.
 package p2putils
 
 import (

shared/pagination/pagination.go

@@ -1,3 +1,4 @@
+// Package pagination contains useful pagination-related helpers.
 package pagination
 
 import (

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 (

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 (

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 (

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 (

shared/runutil/every.go

@@ -1,3 +1,4 @@
+// Package runutil includes helpers for scheduling runnable, periodic functions.
 package runutil
 
 import (

shared/service_registry.go

@@ -1,3 +1,5 @@
+// Package shared includes useful utilities globally accessible in
+// the Prysm monorepo.
 package shared
 
 import (

shared/slotutil/slotticker.go

@@ -1,3 +1,4 @@
+// Package slotutil includes ticker and timer-related functions for eth2.
 package slotutil
 
 import (

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

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 (

shared/traceutil/errors.go

@@ -1,3 +1,4 @@
+// Package traceutil includes useful functions for opentracing annotations.
 package traceutil
 
 import (

shared/tracing/tracer.go

@@ -1,3 +1,5 @@
+// Package tracing sets up jaeger as an opentracing tool
+// for services in Prysm.
 package tracing
 
 import (

shared/trieutil/sparse_merkle.go

@@ -1,3 +1,4 @@
+// Package trieutil defines utilities for sparse merkle tries for eth2.
 package trieutil
 
 import (

shared/version/version.go

@@ -1,3 +1,5 @@
+// Package version executes and returns the version string
+// for the currently running process.
 package version
 
 import (

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 (

slasher/db/db.go

@@ -1,3 +1,4 @@
+// Package db defines a persistent backend for the slasher service.
 package db
 
 import (

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 (

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 (

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 (

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.

slasher/detection/attestations/iface/iface.go

@@ -1,3 +1,4 @@
+// Package iface defines an interface for a slashable attestation detector struct.
 package iface
 
 import (

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 (

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"

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 (

slasher/detection/proposals/iface/iface.go

@@ -1,3 +1,4 @@
+// Package iface defines an interface for a double-proposal detector struct.
 package iface
 
 import (

slasher/detection/testing/utils.go

@@ -1,3 +1,5 @@
+// Package testing includes useful helpers for slasher-related
+// unit tests.
 package testing
 
 import (

slasher/flags/flags.go

@@ -1,3 +1,5 @@
+// Package flags contains all configuration runtime flags for
+// the slasher service.
 package flags
 
 import (

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 (

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 (

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 (

validator/accounts/account.go

@@ -1,3 +1,4 @@
+// Package accounts defines tools to manage an encrypted validator keystore.
 package accounts
 
 import (

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 (

validator/db/db.go

@@ -1,3 +1,4 @@
+// Package db defines a persistent backend for the validator service.
 package db
 
 import (

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 (

validator/flags/flags.go

@@ -1,3 +1,5 @@
+// Package flags contains all configuration runtime flags for
+// the validator service.
 package flags
 
 import (

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 (

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 (