types: comments

types/block_meta.go

@@ -1,10 +1,12 @@
 package types
 
+// BlockMeta contains meta information about a block - namely, it's ID and Header.
 type BlockMeta struct {
 	BlockID BlockID `json:"block_id"` // the block hash and partsethash
 	Header  *Header `json:"header"`   // The block's Header
 }
 
+// NewBlockMeta returns a new BlockMeta from the block and its blockParts.
 func NewBlockMeta(block *Block, blockParts *PartSet) *BlockMeta {
 	return &BlockMeta{
 		BlockID: BlockID{block.Hash(), blockParts.Header()},

types/heartbeat.go

@@ -10,6 +10,8 @@ import (
 	cmn "github.com/tendermint/tmlibs/common"
 )
 
+// Heartbeat is a simple vote-like structure so validators can alert others that
+// they are alive and waiting for transactions.
 type Heartbeat struct {
 	ValidatorAddress data.Bytes       `json:"validator_address"`
 	ValidatorIndex   int              `json:"validator_index"`
@@ -19,6 +21,7 @@ type Heartbeat struct {
 	Signature        crypto.Signature `json:"signature"`
 }
 
+// WriteSignBytes writes the Heartbeat for signing.
 func (heartbeat *Heartbeat) WriteSignBytes(chainID string, w io.Writer, n *int, err *error) {
 	wire.WriteJSON(CanonicalJSONOnceHeartbeat{
 		chainID,
@@ -26,11 +29,13 @@ func (heartbeat *Heartbeat) WriteSignBytes(chainID string, w io.Writer, n *int,
 	}, w, n, err)
 }
 
+// Copy makes a copy of the Heartbeat.
 func (heartbeat *Heartbeat) Copy() *Heartbeat {
 	heartbeatCopy := *heartbeat
 	return &heartbeatCopy
 }
 
+// String returns a string representation of the Heartbeat.
 func (heartbeat *Heartbeat) String() string {
 	if heartbeat == nil {
 		return "nil-heartbeat"

types/keys.go

@@ -1,5 +1,6 @@
 package types
 
+// UNSTABLE
 var (
 	PeerStateKey     = "ConsensusReactor.peerState"
 	PeerMempoolChKey = "MempoolReactor.peerMempoolCh"

types/proposal.go

@@ -15,6 +15,11 @@ var (
 	ErrInvalidBlockPartHash      = errors.New("Error invalid block part hash")
 )
 
+// Proposal defines a block proposal for the consensus.
+// It refers to the block only by its PartSetHeader.
+// It must be signed by the correct proposer for the given Height/Round
+// to be considered valid. It may depend on votes from a previous round,
+// a so-called Proof-of-Lock (POL) round, as noted in the POLRound and POLBlockID.
 type Proposal struct {
 	Height           int              `json:"height"`
 	Round            int              `json:"round"`
@@ -24,7 +29,8 @@ type Proposal struct {
 	Signature        crypto.Signature `json:"signature"`
 }
 
-// polRound: -1 if no polRound.
+// NewProposal returns a new Proposal.
+// If there is no POLRound, polRound should be -1.
 func NewProposal(height int, round int, blockPartsHeader PartSetHeader, polRound int, polBlockID BlockID) *Proposal {
 	return &Proposal{
 		Height:           height,
@@ -35,11 +41,13 @@ func NewProposal(height int, round int, blockPartsHeader PartSetHeader, polRound
 	}
 }
 
+// String returns a string representation of the Proposal.
 func (p *Proposal) String() string {
 	return fmt.Sprintf("Proposal{%v/%v %v (%v,%v) %v}", p.Height, p.Round,
 		p.BlockPartsHeader, p.POLRound, p.POLBlockID, p.Signature)
 }
 
+// WriteSignBytes writes the Proposal bytes for signing
 func (p *Proposal) WriteSignBytes(chainID string, w io.Writer, n *int, err *error) {
 	wire.WriteJSON(CanonicalJSONOnceProposal{
 		ChainID:  chainID,

types/protobuf.go

@@ -4,7 +4,8 @@ import (
 	"github.com/tendermint/abci/types"
 )
 
-// Convert tendermint types to protobuf types
+// TM2PB is used for converting Tendermint types to protobuf types.
+// UNSTABLE
 var TM2PB = tm2pb{}
 
 type tm2pb struct{}

types/services.go

@@ -4,6 +4,8 @@ import (
 	abci "github.com/tendermint/abci/types"
 )
 
+// NOTE: all types in this file are considered UNSTABLE
+
 //------------------------------------------------------
 // blockchain services types
 // NOTE: Interfaces used by RPC must be thread safe!
@@ -12,8 +14,10 @@ import (
 //------------------------------------------------------
 // mempool
 
+// Mempool defines the mempool interface.
 // Updates to the mempool need to be synchronized with committing a block
 // so apps can reset their transient state on Commit
+// UNSTABLE
 type Mempool interface {
 	Lock()
 	Unlock()
@@ -28,6 +32,8 @@ type Mempool interface {
 	EnableTxsAvailable()
 }
 
+// MockMempool is an empty implementation of a Mempool, useful for testing.
+// UNSTABLE
 type MockMempool struct {
 }
 
@@ -44,6 +50,8 @@ func (m MockMempool) EnableTxsAvailable()                          {}
 //------------------------------------------------------
 // blockstore
 
+// BlockStoreRPC is the block store interface used by the RPC.
+// UNSTABLE
 type BlockStoreRPC interface {
 	Height() int
 
@@ -55,6 +63,8 @@ type BlockStoreRPC interface {
 	LoadSeenCommit(height int) *Commit
 }
 
+// BlockStore defines the BlockStore interface.
+// UNSTABLE
 type BlockStore interface {
 	BlockStoreRPC
 	SaveBlock(block *Block, blockParts *PartSet, seenCommit *Commit)

types/tx.go

@@ -10,22 +10,26 @@ import (
 	"github.com/tendermint/tmlibs/merkle"
 )
 
+// Tx represents a transaction, which may contain arbitrary bytes.
 type Tx []byte
 
-// NOTE: this is the hash of the go-wire encoded Tx.
-// Tx has no types at this level, so just length-prefixed.
-// Alternatively, it may make sense to add types here and let
-// []byte be type 0x1 so we can have versioned txs if need be in the future.
+// Hash returns the hash of the go-wire encoded Tx.
+// Tx has no types at this level, so go-wire encoding only adds length-prefix.
+// NOTE: It may make sense to add types here one day and let []byte be type 0x1
+// so we can have versioned txs if need be in the future.
 func (tx Tx) Hash() []byte {
 	return merkle.SimpleHashFromBinary(tx)
 }
 
+// String returns a string representation of the Tx.
 func (tx Tx) String() string {
 	return fmt.Sprintf("Tx{%X}", []byte(tx))
 }
 
+// Txs is a slice of Tx.
 type Txs []Tx
 
+// Hash returns the simple Merkle root hash of the Txs.
 func (txs Txs) Hash() []byte {
 	// Recursive impl.
 	// Copied from tmlibs/merkle to avoid allocations
@@ -51,7 +55,7 @@ func (txs Txs) Index(tx Tx) int {
 	return -1
 }
 
-// Index returns the index of this transaction hash in the list, or -1 if not found
+// IndexByHash returns the index of this transaction hash in the list, or -1 if not found
 func (txs Txs) IndexByHash(hash []byte) int {
 	for i := range txs {
 		if bytes.Equal(txs[i].Hash(), hash) {

types/validator.go

@@ -106,6 +106,8 @@ func (vc validatorCodec) Compare(o1 interface{}, o2 interface{}) int {
 //--------------------------------------------------------------------------------
 // For testing...
 
+// RandValidator returns a randomized validator, useful for testing.
+// UNSTABLE
 func RandValidator(randPower bool, minPower int64) (*Validator, *PrivValidatorFS) {
 	_, tempFilePath := cmn.Tempfile("priv_validator_")
 	privVal := GenPrivValidatorFS(tempFilePath)

types/validator_set.go

@@ -368,7 +368,9 @@ func (ac accumComparable) Less(o interface{}) bool {
 //----------------------------------------
 // For testing
 
+// RandValidatorSet returns a randomized validator set, useful for testing.
 // NOTE: PrivValidator are in order.
+// UNSTABLE
 func RandValidatorSet(numValidators int, votingPower int64) (*ValidatorSet, []*PrivValidatorFS) {
 	vals := make([]*Validator, numValidators)
 	privValidators := make([]*PrivValidatorFS, numValidators)