From 4ab7b7d7cab00cd3a4e0c7b95de8c2ab6b0047ef Mon Sep 17 00:00:00 2001
From: Anton Kaliaev <anton.kalyaev@gmail.com>
Date: Wed, 29 Jul 2020 14:20:39 +0400
Subject: [PATCH] docs: add more details on Vote struct from /consensus_state
 (#5164)

Closes #2743
---
 rpc/swagger/swagger.yaml |  5 ++++-
 types/block.go           | 39 +++++++++++++++++++++++++++++++--------
 types/part_set.go        | 13 +++++++++++++
 types/proposal.go        |  9 +++++++++
 types/validator.go       |  6 ++++++
 types/validator_set.go   |  7 ++++++-
 types/vote.go            | 11 +++++++++++
 types/vote_set.go        | 21 +++++++++++++++++++++
 8 files changed, 101 insertions(+), 10 deletions(-)

diff --git a/rpc/swagger/swagger.yaml b/rpc/swagger/swagger.yaml
index 9a3eb0bd9..780939732 100644
--- a/rpc/swagger/swagger.yaml
+++ b/rpc/swagger/swagger.yaml
@@ -798,7 +798,10 @@ paths:
         Not safe to call from inside the ABCI application during a block execution.
       responses:
         200:
-          description: consensus state results.
+          description: |
+            Complete consensus state.
+
+            See https://pkg.go.dev/github.com/tendermint/tendermint/types?tab=doc#Vote.String for Vote string description.
           content:
             application/json:
               schema:
diff --git a/types/block.go b/types/block.go
index c5d62df9f..708860b9a 100644
--- a/types/block.go
+++ b/types/block.go
@@ -188,11 +188,19 @@ func (b *Block) Size() int {
 }
 
 // String returns a string representation of the block
+//
+// See StringIndented.
 func (b *Block) String() string {
 	return b.StringIndented("")
 }
 
-// StringIndented returns a string representation of the block
+// StringIndented returns an indented String.
+//
+// Header
+// Data
+// Evidence
+// LastCommit
+// Hash
 func (b *Block) StringIndented(indent string) string {
 	if b == nil {
 		return "nil-Block"
@@ -210,12 +218,12 @@ func (b *Block) StringIndented(indent string) string {
 		indent, b.Hash())
 }
 
-// StringShort returns a shortened string representation of the block
+// StringShort returns a shortened string representation of the block.
 func (b *Block) StringShort() string {
 	if b == nil {
 		return "nil-Block"
 	}
-	return fmt.Sprintf("Block#%v", b.Hash())
+	return fmt.Sprintf("Block#%X", b.Hash())
 }
 
 // ToProto converts Block to protobuf
@@ -473,7 +481,7 @@ func (h *Header) Hash() tmbytes.HexBytes {
 	})
 }
 
-// StringIndented returns a string representation of the header
+// StringIndented returns an indented string representation of the header.
 func (h *Header) StringIndented(indent string) string {
 	if h == nil {
 		return "nil-Header"
@@ -618,6 +626,12 @@ func (cs CommitSig) Absent() bool {
 	return cs.BlockIDFlag == BlockIDFlagAbsent
 }
 
+// CommitSig returns a string representation of CommitSig.
+//
+// 1. first 6 bytes of signature
+// 2. first 6 bytes of validator address
+// 3. block ID flag
+// 4. timestamp
 func (cs CommitSig) String() string {
 	return fmt.Sprintf("CommitSig{%X by %X on %v @ %s}",
 		tmbytes.Fingerprint(cs.Signature),
@@ -890,7 +904,7 @@ func (commit *Commit) Hash() tmbytes.HexBytes {
 	return commit.hash
 }
 
-// StringIndented returns a string representation of the commit
+// StringIndented returns a string representation of the commit.
 func (commit *Commit) StringIndented(indent string) string {
 	if commit == nil {
 		return "nil-Commit"
@@ -1019,11 +1033,15 @@ func (sh SignedHeader) ValidateBasic(chainID string) error {
 	return nil
 }
 
+// String returns a string representation of SignedHeader.
 func (sh SignedHeader) String() string {
 	return sh.StringIndented("")
 }
 
-// StringIndented returns a string representation of the SignedHeader.
+// StringIndented returns an indented string representation of SignedHeader.
+//
+// Header
+// Commit
 func (sh SignedHeader) StringIndented(indent string) string {
 	return fmt.Sprintf(`SignedHeader{
 %s  %v
@@ -1104,7 +1122,7 @@ func (data *Data) Hash() tmbytes.HexBytes {
 	return data.hash
 }
 
-// StringIndented returns a string representation of the transactions
+// StringIndented returns an indented string representation of the transactions.
 func (data *Data) StringIndented(indent string) string {
 	if data == nil {
 		return "nil-Data"
@@ -1299,7 +1317,12 @@ func (blockID BlockID) IsComplete() bool {
 		len(blockID.PartSetHeader.Hash) == tmhash.Size
 }
 
-// String returns a human readable string representation of the BlockID
+// String returns a human readable string representation of the BlockID.
+//
+// 1. hash
+// 2. part set header
+//
+// See PartSetHeader#String
 func (blockID BlockID) String() string {
 	return fmt.Sprintf(`%v:%v`, blockID.Hash, blockID.PartSetHeader)
 }
diff --git a/types/part_set.go b/types/part_set.go
index 5f730aa3e..6b00a5f78 100644
--- a/types/part_set.go
+++ b/types/part_set.go
@@ -37,10 +37,16 @@ func (part *Part) ValidateBasic() error {
 	return nil
 }
 
+// String returns a string representation of Part.
+//
+// See StringIndented.
 func (part *Part) String() string {
 	return part.StringIndented("")
 }
 
+// StringIndented returns an indented Part.
+//
+// See merkle.Proof#StringIndented
 func (part *Part) StringIndented(indent string) string {
 	return fmt.Sprintf(`Part{#%v
 %s  Bytes: %X...
@@ -90,6 +96,10 @@ type PartSetHeader struct {
 	Hash  tmbytes.HexBytes `json:"hash"`
 }
 
+// String returns a string representation of PartSetHeader.
+//
+// 1. total number of parts
+// 2. first 6 bytes of the hash
 func (psh PartSetHeader) String() string {
 	return fmt.Sprintf("%v:%X", psh.Total, tmbytes.Fingerprint(psh.Hash))
 }
@@ -322,6 +332,9 @@ func (psr *PartSetReader) Read(p []byte) (n int, err error) {
 	return psr.Read(p)
 }
 
+// StringShort returns a short version of String.
+//
+// (Count of Total)
 func (ps *PartSet) StringShort() string {
 	if ps == nil {
 		return "nil-PartSet"
diff --git a/types/proposal.go b/types/proposal.go
index 45a781963..f714de309 100644
--- a/types/proposal.go
+++ b/types/proposal.go
@@ -80,6 +80,15 @@ func (p *Proposal) ValidateBasic() error {
 }
 
 // String returns a string representation of the Proposal.
+//
+// 1. height
+// 2. round
+// 3. block ID
+// 4. POL round
+// 5. first 6 bytes of signature
+// 6. timestamp
+//
+// See BlockID#String.
 func (p *Proposal) String() string {
 	return fmt.Sprintf("Proposal{%v/%v (%v, %v) %X @ %s}",
 		p.Height,
diff --git a/types/validator.go b/types/validator.go
index c56a6bc07..961b833e4 100644
--- a/types/validator.go
+++ b/types/validator.go
@@ -83,6 +83,12 @@ func (v *Validator) CompareProposerPriority(other *Validator) *Validator {
 	}
 }
 
+// String returns a string representation of String.
+//
+// 1. address
+// 2. public key
+// 3. voting power
+// 4. proposer priority
 func (v *Validator) String() string {
 	if v == nil {
 		return "nil-Validator"
diff --git a/types/validator_set.go b/types/validator_set.go
index b8e0c847f..5b9951c7e 100644
--- a/types/validator_set.go
+++ b/types/validator_set.go
@@ -846,11 +846,16 @@ func (e ErrNotEnoughVotingPowerSigned) Error() string {
 
 //----------------
 
+// String returns a string representation of ValidatorSet.
+//
+// See StringIndented.
 func (vals *ValidatorSet) String() string {
 	return vals.StringIndented("")
 }
 
-// StringIndented returns an intended string representation of ValidatorSet.
+// StringIndented returns an intended String.
+//
+// See Validator#String.
 func (vals *ValidatorSet) StringIndented(indent string) string {
 	if vals == nil {
 		return "nil-ValidatorSet"
diff --git a/types/vote.go b/types/vote.go
index 6a8b31736..355e8131b 100644
--- a/types/vote.go
+++ b/types/vote.go
@@ -103,6 +103,17 @@ func (vote *Vote) Copy() *Vote {
 	return &voteCopy
 }
 
+// String returns a string representation of Vote.
+//
+// 1. validator index
+// 2. first 6 bytes of validator address
+// 3. height
+// 4. round,
+// 5. type byte
+// 6. type string
+// 7. first 6 bytes of block hash
+// 8. first 6 bytes of signature
+// 9. timestamp
 func (vote *Vote) String() string {
 	if vote == nil {
 		return nilVoteStr
diff --git a/types/vote_set.go b/types/vote_set.go
index 6c2b08f67..bf72b18cb 100644
--- a/types/vote_set.go
+++ b/types/vote_set.go
@@ -442,6 +442,9 @@ func (voteSet *VoteSet) TwoThirdsMajority() (blockID BlockID, ok bool) {
 //--------------------------------------------------------------------------------
 // Strings and JSON
 
+// String returns a string representation of VoteSet.
+//
+// See StringIndented.
 func (voteSet *VoteSet) String() string {
 	if voteSet == nil {
 		return "nil-VoteSet"
@@ -449,9 +452,18 @@ func (voteSet *VoteSet) String() string {
 	return voteSet.StringIndented("")
 }
 
+// StringIndented returns an indented String.
+//
+// Height Round Type
+// Votes
+// Votes bit array
+// 2/3+ majority
+//
+// See Vote#String.
 func (voteSet *VoteSet) StringIndented(indent string) string {
 	voteSet.mtx.Lock()
 	defer voteSet.mtx.Unlock()
+
 	voteStrings := make([]string, len(voteSet.votes))
 	for i, vote := range voteSet.votes {
 		if vote == nil {
@@ -528,6 +540,15 @@ func (voteSet *VoteSet) voteStrings() []string {
 	return voteStrings
 }
 
+// StringShort returns a short representation of VoteSet.
+//
+// 1. height
+// 2. round
+// 3. signed msg type
+// 4. first 2/3+ majority
+// 5. fraction of voted power
+// 6. votes bit array
+// 7. 2/3+ majority for each peer
 func (voteSet *VoteSet) StringShort() string {
 	if voteSet == nil {
 		return "nil-VoteSet"