Add doc comments

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

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

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) }

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