From 6997a3ce4347b4f59de2c050fafa8073e37f3b2d Mon Sep 17 00:00:00 2001
From: likhita-809 <78951027+likhita-809@users.noreply.github.com>
Date: Tue, 13 Jul 2021 04:47:01 +0530
Subject: [PATCH] docs: Add godocs to GasMeter methods (#9665)

<!--
The default pull request template is for types feat, fix, or refactor.
For other templates, add one of the following parameters to the url:
- template=docs.md
- template=other.md
-->

## Description

ref: #9651

This is a follow-up PR of adding godocs to GasMeter methods

---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [ ] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] added `!` to the type prefix if API or client breaking change
- [ ] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [ ] provided a link to the relevant issue or specification
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md`
- [ ] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [ ] updated the relevant documentation or specification
- [ ] reviewed "Files changed" and left comments if necessary
- [ ] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)
---
 store/types/gas.go | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/store/types/gas.go b/store/types/gas.go
index dc7e44b3c2e4..9999630a662a 100644
--- a/store/types/gas.go
+++ b/store/types/gas.go
@@ -63,10 +63,12 @@ func NewGasMeter(limit Gas) GasMeter {
 	}
 }
 
+// GasConsumed returns the gas consumed from the GasMeter.
 func (g *basicGasMeter) GasConsumed() Gas {
 	return g.consumed
 }
 
+// GasRemaining returns the gas left in the GasMeter.
 func (g *basicGasMeter) GasRemaining() Gas {
 	if g.IsPastLimit() {
 		return 0
@@ -74,10 +76,15 @@ func (g *basicGasMeter) GasRemaining() Gas {
 	return g.limit - g.consumed
 }
 
+// Limit returns the gas limit of the GasMeter.
 func (g *basicGasMeter) Limit() Gas {
 	return g.limit
 }
 
+// GasConsumedToLimit returns the gas limit if gas consumed is past the limit,
+// otherwise it returns the consumed gas.
+// NOTE: This behaviour is only called when recovering from panic when
+// BlockGasMeter consumes gas past the limit.
 func (g *basicGasMeter) GasConsumedToLimit() Gas {
 	if g.IsPastLimit() {
 		return g.limit
@@ -95,6 +102,7 @@ func addUint64Overflow(a, b uint64) (uint64, bool) {
 	return a + b, false
 }
 
+// ConsumeGas adds the given amount of gas to the gas consumed and panics if it overflows the limit or out of gas.
 func (g *basicGasMeter) ConsumeGas(amount Gas, descriptor string) {
 	var overflow bool
 	// TODO: Should we set the consumed field after overflow checking?
@@ -122,14 +130,17 @@ func (g *basicGasMeter) RefundGas(amount Gas, descriptor string) {
 	g.consumed -= amount
 }
 
+// IsPastLimit returns true if gas consumed is past limit, otherwise it returns false.
 func (g *basicGasMeter) IsPastLimit() bool {
 	return g.consumed > g.limit
 }
 
+// IsOutOfGas returns true if gas consumed is greater than or equal to gas limit, otherwise it returns false.
 func (g *basicGasMeter) IsOutOfGas() bool {
 	return g.consumed >= g.limit
 }
 
+// String returns the BasicGasMeter's gas limit and gas consumed.
 func (g *basicGasMeter) String() string {
 	return fmt.Sprintf("BasicGasMeter:\n  limit: %d\n  consumed: %d", g.limit, g.consumed)
 }
@@ -145,22 +156,28 @@ func NewInfiniteGasMeter() GasMeter {
 	}
 }
 
+// GasConsumed returns the gas consumed from the GasMeter.
 func (g *infiniteGasMeter) GasConsumed() Gas {
 	return g.consumed
 }
 
+// GasConsumedToLimit returns the gas consumed from the GasMeter since the gas is not confined to a limit.
+// NOTE: This behaviour is only called when recovering from panic when BlockGasMeter consumes gas past the limit.
 func (g *infiniteGasMeter) GasConsumedToLimit() Gas {
 	return g.consumed
 }
 
+// GasRemaining returns MaxUint64 since limit is not confined in infiniteGasMeter.
 func (g *infiniteGasMeter) GasRemaining() Gas {
 	return math.MaxUint64
 }
 
+// Limit returns MaxUint64 since limit is not confined in infiniteGasMeter.
 func (g *infiniteGasMeter) Limit() Gas {
 	return math.MaxUint64
 }
 
+// ConsumeGas adds the given amount of gas to the gas consumed and panics if it overflows the limit.
 func (g *infiniteGasMeter) ConsumeGas(amount Gas, descriptor string) {
 	var overflow bool
 	// TODO: Should we set the consumed field after overflow checking?
@@ -184,14 +201,17 @@ func (g *infiniteGasMeter) RefundGas(amount Gas, descriptor string) {
 	g.consumed -= amount
 }
 
+// IsPastLimit returns false since the gas limit is not confined.
 func (g *infiniteGasMeter) IsPastLimit() bool {
 	return false
 }
 
+// IsOutOfGas returns false since the gas limit is not confined.
 func (g *infiniteGasMeter) IsOutOfGas() bool {
 	return false
 }
 
+// String returns the InfiniteGasMeter's gas consumed.
 func (g *infiniteGasMeter) String() string {
 	return fmt.Sprintf("InfiniteGasMeter:\n  consumed: %d", g.consumed)
 }