types: comments

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,