From cf2039fe6204561a8272a9f19da4eedec2e13511 Mon Sep 17 00:00:00 2001
From: Nick Johnson <arachnid@notdot.net>
Date: Tue, 25 Sep 2018 14:50:04 +0100
Subject: [PATCH] Add doc comments

---
 accounts/abi/bind/backends/simulated.go | 3 +++
 eth/filters/api.go                      | 3 +++
 eth/filters/filter.go                   | 4 ++++
 rpc/types.go                            | 6 ++++++
 4 files changed, 16 insertions(+)

diff --git a/accounts/abi/bind/backends/simulated.go b/accounts/abi/bind/backends/simulated.go
index 110bf18346..09c7f3b5da 100644
--- a/accounts/abi/bind/backends/simulated.go
+++ b/accounts/abi/bind/backends/simulated.go
@@ -319,6 +319,9 @@ func (b *SimulatedBackend) SendTransaction(ctx context.Context, tx *types.Transa
 	return nil
 }
 
+// getBlockHash returns the block hash of the requested block.
+// `hash` is used if supplied; if not the canonoical block at `number` is looked up.
+// If neither is supplied, the latest canonical block hash is returned.
 func (b *SimulatedBackend) getBlockHash(number *big.Int, hash *common.Hash) (common.Hash, error) {
 	if hash != nil {
 		return *hash, nil
diff --git a/eth/filters/api.go b/eth/filters/api.go
index 61eddcc662..4f8537608c 100644
--- a/eth/filters/api.go
+++ b/eth/filters/api.go
@@ -320,6 +320,9 @@ func (api *PublicFilterAPI) NewFilter(crit FilterCriteria) (rpc.ID, error) {
 	return logsSub.ID, nil
 }
 
+// getBlockHash returns the block hash of the requested block.
+// `hash` is used if supplied; if not the canonoical block at `number` is looked up.
+// If neither is supplied, the latest canonical block hash is returned.
 func (api *PublicFilterAPI) getBlockHash(ctx context.Context, number *big.Int, hash *common.Hash) (common.Hash, error) {
 	if hash != nil {
 		return *hash, nil
diff --git a/eth/filters/filter.go b/eth/filters/filter.go
index b2aad2e41e..22d683d5a8 100644
--- a/eth/filters/filter.go
+++ b/eth/filters/filter.go
@@ -115,6 +115,9 @@ func newFilter(backend Backend, addresses []common.Address, topics [][]common.Ha
 	}
 }
 
+// findCommonAncestor returns the highest numbered block that is the ancestor of
+// both `begin` and `end`. `end` must have a block number greater than or equal
+// to `begin`.
 func (f *Filter) findCommonAncestor(ctx context.Context, begin, end *types.Header) (*types.Header, bool, error) {
 	var err error
 	var mainChain bool
@@ -153,6 +156,7 @@ func (f *Filter) findCommonAncestor(ctx context.Context, begin, end *types.Heade
 	return end, mainChain, nil
 }
 
+// logList allows sorting event logs by block number and log index
 type logList []*types.Log
 
 func (l logList) Len() int      { return len(l) }
diff --git a/rpc/types.go b/rpc/types.go
index 0b09763f1d..e114fee9e2 100644
--- a/rpc/types.go
+++ b/rpc/types.go
@@ -165,17 +165,22 @@ func (bn BlockNumber) Int64() int64 {
 	return (int64)(bn)
 }
 
+// BlockNumberOrHash permits JSON deserialization and parsing of a value that
+// can be either a block number or block hash.
 type BlockNumberOrHash string
 
+// UnmarshalJSON parses the supplied JSON fragment as a BlockNumberOrHash.
 func (bnh *BlockNumberOrHash) UnmarshalJSON(data []byte) error {
 	*bnh = BlockNumberOrHash(data)
 	return nil
 }
 
+// IsHash returns true iff the value is a block hash.
 func (bnh BlockNumberOrHash) IsHash() bool {
 	return bnh[0] == '"' && bnh[len(bnh)-1] == '"' && len(bnh) == 44
 }
 
+// Hash returns the hash value, or nil if the value is not a hash.
 func (bnh BlockNumberOrHash) Hash() *common.Hash {
 	if !bnh.IsHash() {
 		return nil
@@ -184,6 +189,7 @@ func (bnh BlockNumberOrHash) Hash() *common.Hash {
 	return &hash
 }
 
+// Number returns the numeric value, or 0 if the value is not numeric.
 func (bnh BlockNumberOrHash) Number() int64 {
 	var bn BlockNumber
 	(&bn).UnmarshalJSON([]byte(bnh))