[Feature]: Update block gas documentation

[colin-axner]

Summary

The block gas documentation needs to be updated, see here

Problem Definition

Older version of this doc:

When a new transaction is being processed via DeliverTx, the current value of BlockGasMeter is checked to see if it is above the limit. If it is, DeliverTx returns immediately. This can happen even with the first transaction in a block, as BeginBlock itself can consume gas. If not, the transaction is processed normally. At the end of DeliverTx, the gas tracked by ctx.BlockGasMeter() is increased by the amount consumed to process the transaction:

This seems to imply block gas is consumed on begin block (and maybe even end block). The reality is that a module could consume block gas through the context (but this could happen at any point)

The newer docs:

When a new transaction is being processed via FinalizeBlock, the current value of BlockGasMeter is checked to see if it is above the limit. If it is, the transaction fails and returned to the consensus engine as a failed transaction. This can happen even with the first transaction in a block, as FinalizeBlock itself can consume gas. If not, the transaction is processed normally. At the end of FinalizeBlock, the gas tracked by ctx.BlockGasMeter() is increased by the amount consumed to process the transaction:

The references to begin block got replaced with FinalizeBlock which also executes tx's so now it is quite confusing to read.

Proposal

Update the documentation to specify exactly when baseapp consumes block gas