Package Godocs improvements and additions (osmosis-labs#2064)

* ante, app, cmd, osmomath package doc additions * wasmbindings, epochs, and gamm doc additions * modules, proto godocs additions * proto godocs additions * make proto-gen * godocs in all module.go; package godocs * sync w main * godocs naming conventions followed * Update ante/sendblock.go Co-authored-by: Roman <[email protected]> * Update app/apptesting/gamm.go Co-authored-by: Roman <[email protected]> * Update app/apptesting/gamm.go Co-authored-by: Roman <[email protected]> * Update app/apptesting/gamm.go Co-authored-by: Roman <[email protected]> * Update app/keepers/keys.go Co-authored-by: Roman <[email protected]> * Update app/keepers/keys.go Co-authored-by: Roman <[email protected]> * Update app/modules.go Co-authored-by: Roman <[email protected]> * Update app/params/config.go Co-authored-by: Roman <[email protected]> * Update cmd/osmosisd/cmd/init.go Co-authored-by: Roman <[email protected]> * Update app/apptesting/test_suite.go Co-authored-by: Matt, Park <[email protected]> * Update app/apptesting/test_suite.go Co-authored-by: Matt, Park <[email protected]> * Update app/forks.go Co-authored-by: Matt, Park <[email protected]> * Update cmd/osmosisd/cmd/genesis.go Co-authored-by: Matt, Park <[email protected]> * Update cmd/osmosisd/cmd/testnet.go Co-authored-by: Matt, Park <[email protected]> * Update proto/osmosis/gamm/pool-models/balancer/tx/tx.proto Co-authored-by: Matt, Park <[email protected]> * Update app/keepers/keys.go Co-authored-by: Roman <[email protected]> * Update osmomath/decimal.go Co-authored-by: Matt, Park <[email protected]> * Update proto/osmosis/pool-incentives/v1beta1/query.proto Co-authored-by: Matt, Park <[email protected]> * Update wasmbinding/message_plugin.go Co-authored-by: Matt, Park <[email protected]> * Update wasmbinding/message_plugin.go Co-authored-by: Matt, Park <[email protected]> * Update osmomath/decimal.go Co-authored-by: Matt, Park <[email protected]> * docs clarifications * make all * indirect fix Co-authored-by: Roman <[email protected]> Co-authored-by: Matt, Park <[email protected]>
tj327 · Jul 19, 2022 · ce51825 · ce51825
1 parent 69126dd
commit ce51825
Show file tree

Hide file tree

Showing 51 changed files with 241 additions and 21 deletions.
diff --git a/ante/sendblock.go b/ante/sendblock.go
@@ -14,12 +14,14 @@ type SendBlockOptions struct {
 	PermittedOnlySendTo map[string]string
 }
 
+// NewSendBlockOptions returns options for sending new blocks.
 func NewSendBlockOptions(appOpts servertypes.AppOptions) SendBlockOptions {
 	return SendBlockOptions{
 		PermittedOnlySendTo: parsePermittedOnlySendTo(appOpts),
 	}
 }
 
+// parsePermittedOnlySendTo parses the mapping PermittedOnlySendTo.
 func parsePermittedOnlySendTo(opts servertypes.AppOptions) map[string]string {
 	valueInterface := opts.Get("permitted-only-send-to")
 	if valueInterface == nil {
@@ -32,12 +34,14 @@ type SendBlockDecorator struct {
 	Options SendBlockOptions
 }
 
+// NewSendBlockDecorator are a part of auth module AnteDecorators that are recursively chained together into a single AntiHandler.
 func NewSendBlockDecorator(options SendBlockOptions) *SendBlockDecorator {
 	return &SendBlockDecorator{
 		Options: options, // TODO: hydrate from configuration
 	}
 }
 
+// AnteHandle is used for performing basic validity checks on a transaction such that it can be thrown out of the mempool.
 func (decorator *SendBlockDecorator) AnteHandle(
 	ctx sdk.Context,
 	tx sdk.Tx,

diff --git a/app/app.go b/app/app.go
@@ -132,6 +132,7 @@ type OsmosisApp struct {
 	configurator module.Configurator
 }
 
+// init sets DefaultNodeHome to default osmosisd install location.
 func init() {
 	userHomeDir, err := os.UserHomeDir()
 	if err != nil {

diff --git a/app/apptesting/gamm.go b/app/apptesting/gamm.go
@@ -14,7 +14,7 @@ var DefaultAcctFunds sdk.Coins = sdk.NewCoins(
 	sdk.NewCoin("baz", sdk.NewInt(10000000)),
 )
 
-// Returns a Univ2 pool with the initial liquidity being the provided balances
+// PrepareUni2PoolWithAssets returns a Univ2 pool with the initial liquidity being the provided balances.
 func (s *KeeperTestHelper) PrepareUni2PoolWithAssets(asset1, asset2 sdk.Coin) uint64 {
 	return s.PrepareBalancerPoolWithPoolAsset(
 		[]balancer.PoolAsset{
@@ -30,6 +30,7 @@ func (s *KeeperTestHelper) PrepareUni2PoolWithAssets(asset1, asset2 sdk.Coin) ui
 	)
 }
 
+// PrepareBalancerPool returns a Balancer pool's pool-ID with pool params set in PrepareBalancerPoolWithPoolParams.
 func (s *KeeperTestHelper) PrepareBalancerPool() uint64 {
 	poolId := s.PrepareBalancerPoolWithPoolParams(balancer.PoolParams{
 		SwapFee: sdk.NewDec(0),
@@ -51,6 +52,7 @@ func (s *KeeperTestHelper) PrepareBalancerPool() uint64 {
 	return poolId
 }
 
+// PrepareBalancerPoolWithPoolParams sets up a Balancer pool with poolParams.
 func (s *KeeperTestHelper) PrepareBalancerPoolWithPoolParams(poolParams balancer.PoolParams) uint64 {
 	// Mint some assets to the account.
 	s.FundAcc(s.TestAccs[0], DefaultAcctFunds)
@@ -75,6 +77,7 @@ func (s *KeeperTestHelper) PrepareBalancerPoolWithPoolParams(poolParams balancer
 	return poolId
 }
 
+// PrepareBalancerPoolWithPoolAsset sets up a Balancer pool with an array of assets.
 func (s *KeeperTestHelper) PrepareBalancerPoolWithPoolAsset(assets []balancer.PoolAsset) uint64 {
 	s.Require().Len(assets, 2)
 

diff --git a/app/apptesting/test_suite.go b/app/apptesting/test_suite.go
@@ -39,6 +39,7 @@ type KeeperTestHelper struct {
 	TestAccs    []sdk.AccAddress
 }
 
+// Setup sets up basic environment for suite (App, Ctx, and test accounts)
 func (s *KeeperTestHelper) Setup() {
 	s.App = app.Setup(false)
 	s.Ctx = s.App.BaseApp.NewContext(false, tmtypes.Header{Height: 1, ChainID: "osmosis-1", Time: time.Now().UTC()})
@@ -50,6 +51,7 @@ func (s *KeeperTestHelper) Setup() {
 	s.TestAccs = CreateRandomAccounts(3)
 }
 
+// CreateTestContext creates a test context.
 func (s *KeeperTestHelper) CreateTestContext() sdk.Context {
 	db := dbm.NewMemDB()
 	logger := log.NewNopLogger()
@@ -59,11 +61,13 @@ func (s *KeeperTestHelper) CreateTestContext() sdk.Context {
 	return sdk.NewContext(ms, tmtypes.Header{}, false, logger)
 }
 
+// FundAcc funds target address with specified amount.
 func (s *KeeperTestHelper) FundAcc(acc sdk.AccAddress, amounts sdk.Coins) {
 	err := simapp.FundAccount(s.App.BankKeeper, s.Ctx, acc, amounts)
 	s.Require().NoError(err)
 }
 
+// SetupValidator sets up a validator and returns the ValAddress.
 func (s *KeeperTestHelper) SetupValidator(bondStatus stakingtypes.BondStatus) sdk.ValAddress {
 	valPub := secp256k1.GenPrivKey().PubKey()
 	valAddr := sdk.ValAddress(valPub.Address())
@@ -98,10 +102,12 @@ func (s *KeeperTestHelper) SetupValidator(bondStatus stakingtypes.BondStatus) sd
 	return valAddr
 }
 
+// SetupTokenFactory sets up a token module account for the TokenFactoryKeeper.
 func (s *KeeperTestHelper) SetupTokenFactory() {
 	s.App.TokenFactoryKeeper.CreateModuleAccount(s.Ctx)
 }
 
+// BeginNewBlock starts a new block.
 func (s *KeeperTestHelper) BeginNewBlock(executeNextEpoch bool) {
 	var valAddr []byte
 
@@ -120,6 +126,7 @@ func (s *KeeperTestHelper) BeginNewBlock(executeNextEpoch bool) {
 	s.BeginNewBlockWithProposer(executeNextEpoch, valAddr)
 }
 
+// BeginNewBlockWithProposer begins a new block with a proposer.
 func (s *KeeperTestHelper) BeginNewBlockWithProposer(executeNextEpoch bool, proposer sdk.ValAddress) {
 	validator, found := s.App.StakingKeeper.GetValidator(s.Ctx, proposer)
 	s.Assert().True(found)
@@ -152,11 +159,13 @@ func (s *KeeperTestHelper) BeginNewBlockWithProposer(executeNextEpoch bool, prop
 	s.App.BeginBlocker(s.Ctx, reqBeginBlock)
 }
 
+// EndBlock ends the block.
 func (s *KeeperTestHelper) EndBlock() {
 	reqEndBlock := abci.RequestEndBlock{Height: s.Ctx.BlockHeight()}
 	s.App.EndBlocker(s.Ctx, reqEndBlock)
 }
 
+// AllocateRewardsToValidator allocates reward tokens to a distribution module then allocates rewards to the validator address.
 func (s *KeeperTestHelper) AllocateRewardsToValidator(valAddr sdk.ValAddress, rewardAmt sdk.Int) {
 	validator, found := s.App.StakingKeeper.GetValidator(s.Ctx, valAddr)
 	s.Require().True(found)
@@ -250,6 +259,7 @@ func (s *KeeperTestHelper) SwapAndSetSpotPrice(poolId uint64, fromAsset sdk.Coin
 	return spotPrice
 }
 
+// LockTokens funds an account, locks tokens and returns a lockID.
 func (s *KeeperTestHelper) LockTokens(addr sdk.AccAddress, coins sdk.Coins, duration time.Duration) (lockID uint64) {
 	msgServer := lockupkeeper.NewMsgServerImpl(s.App.LockupKeeper)
 	s.FundAcc(addr, coins)
@@ -260,6 +270,7 @@ func (s *KeeperTestHelper) LockTokens(addr sdk.AccAddress, coins sdk.Coins, dura
 	return msgResponse.ID
 }
 
+// BuildTx builds a transaction.
 func (s *KeeperTestHelper) BuildTx(
 	txBuilder client.TxBuilder,
 	msgs []sdk.Msg,

diff --git a/app/config.go b/app/config.go
@@ -47,6 +47,7 @@ func DefaultConfig() network.Config {
 	}
 }
 
+// NewAppConstructor returns a new Osmosis app given encoding type configs.
 func NewAppConstructor(encodingCfg params.EncodingConfig) network.AppConstructor {
 	return func(val network.Validator) servertypes.Application {
 		return NewOsmosisApp(

diff --git a/app/forks.go b/app/forks.go
@@ -4,7 +4,7 @@ import (
 	sdk "github.com/cosmos/cosmos-sdk/types"
 )
 
-// BeginBlockForks is intended to be ran in.
+// BeginBlockForks is intended to be ran in a chain upgrade.
 func BeginBlockForks(ctx sdk.Context, app *OsmosisApp) {
 	for _, fork := range Forks {
 		if ctx.BlockHeight() == fork.UpgradeHeight {

diff --git a/app/keepers/keepers.go b/app/keepers/keepers.go
@@ -118,6 +118,7 @@ type AppKeepers struct {
 	memKeys map[string]*sdk.MemoryStoreKey
 }
 
+// InitNormalKeepers initializes all 'normal' keepers (account, app, bank, auth, staking, distribution, slashing, transfer, gamm, IBC router, pool incentives, governance, mint, txfees keepers).
 func (appKeepers *AppKeepers) InitNormalKeepers(
 	appCodec codec.Codec,
 	bApp *baseapp.BaseApp,
@@ -367,6 +368,7 @@ func (appKeepers *AppKeepers) InitNormalKeepers(
 	appKeepers.GovKeeper = &govKeeper
 }
 
+// InitSpecialKeepers initiates special keepers (crisis appkeeper, upgradekeeper, params keeper)
 func (appKeepers *AppKeepers) InitSpecialKeepers(
 	appCodec codec.Codec,
 	bApp *baseapp.BaseApp,
@@ -433,6 +435,7 @@ func (appKeepers *AppKeepers) initParamsKeeper(appCodec codec.BinaryCodec, legac
 	return paramsKeeper
 }
 
+// SetupHooks sets up hooks for modules.
 func (appKeepers *AppKeepers) SetupHooks() {
 	// For every module that has hooks set on it,
 	// you must check InitNormalKeepers to ensure that its not passed by de-reference

diff --git a/app/keepers/keys.go b/app/keepers/keys.go
@@ -6,6 +6,7 @@ import (
 	paramstypes "github.com/cosmos/cosmos-sdk/x/params/types"
 )
 
+// GenerateKeys generates new keys (KV Store, Transient store, and memory store).
 func (appKeepers *AppKeepers) GenerateKeys() {
 	// Define what keys will be used in the cosmos-sdk key/value store.
 	// Cosmos-SDK modules each have a "key" that allows the application to reference what they've stored on the chain.
@@ -18,19 +19,23 @@ func (appKeepers *AppKeepers) GenerateKeys() {
 	appKeepers.memKeys = sdk.NewMemoryStoreKeys(capabilitytypes.MemStoreKey)
 }
 
+// GetSubspace gets existing substore from keeper.
 func (appKeepers *AppKeepers) GetSubspace(moduleName string) paramstypes.Subspace {
 	subspace, _ := appKeepers.ParamsKeeper.GetSubspace(moduleName)
 	return subspace
 }
 
+// GetKVStoreKey gets KV Store keys.
 func (appKeepers *AppKeepers) GetKVStoreKey() map[string]*sdk.KVStoreKey {
 	return appKeepers.keys
 }
 
+// GetTransientStoreKey gets Transient Store keys.
 func (appKeepers *AppKeepers) GetTransientStoreKey() map[string]*sdk.TransientStoreKey {
 	return appKeepers.tkeys
 }
 
+// GetMemoryStoreKey get memory Store keys.
 func (appKeepers *AppKeepers) GetMemoryStoreKey() map[string]*sdk.MemoryStoreKey {
 	return appKeepers.memKeys
 }

diff --git a/app/modules.go b/app/modules.go
@@ -162,6 +162,7 @@ func orderBeginBlockers(allModuleNames []string) []string {
 	return ord.TotalOrdering()
 }
 
+// OrderEndBlockers returns EndBlockers (crisis, govtypes, staking) with no relative order.
 func OrderEndBlockers(allModuleNames []string) []string {
 	ord := partialord.NewPartialOrdering(allModuleNames)
 	// only Osmosis modules with endblock code are: crisis, govtypes, staking

diff --git a/app/params/config.go b/app/params/config.go
@@ -36,6 +36,7 @@ func init() {
 	RegisterDenoms()
 }
 
+// RegisterDenoms registers token denoms.
 func RegisterDenoms() {
 	err := sdk.RegisterDenom(HumanCoinUnit, sdk.OneDec())
 	if err != nil {
@@ -47,6 +48,7 @@ func RegisterDenoms() {
 	}
 }
 
+// SetAddressPrefixes builds the Config with Bech32 addressPrefix and publKeyPrefix for accounts, validators, and consensus nodes and verifies that addreeses have correct format.
 func SetAddressPrefixes() {
 	config := sdk.GetConfig()
 	config.SetBech32PrefixForAccount(Bech32PrefixAccAddr, Bech32PrefixAccPub)

diff --git a/cmd/osmosisd/cmd/balances_from_state_export.go b/cmd/osmosisd/cmd/balances_from_state_export.go
@@ -43,6 +43,7 @@ type DerivedAccount struct {
 	TotalBalances       sdk.Coins            `json:"total_balances"`
 }
 
+// newDerivedAccount returns a new derived account.
 func newDerivedAccount(address string) DerivedAccount {
 	return DerivedAccount{
 		Address:        address,
@@ -53,6 +54,7 @@ func newDerivedAccount(address string) DerivedAccount {
 	}
 }
 
+// underlyingCoins returns liquidity pool's underlying coin balances.
 func underlyingCoins(originCoins sdk.Coins, pools map[string]gammtypes.PoolI) sdk.Coins {
 	balances := sdk.Coins{}
 	convertAgain := false
@@ -115,6 +117,7 @@ func underlyingCoinsForSelectPools(
 	return balancesByPool
 }
 
+// getGenStateFromPath returns a JSON genState message from inputted path.
 func getGenStateFromPath(genesisFilePath string) (map[string]json.RawMessage, error) {
 	genState := make(map[string]json.RawMessage)
 

diff --git a/cmd/osmosisd/cmd/forceprune.go b/cmd/osmosisd/cmd/forceprune.go
@@ -30,7 +30,7 @@ const (
 	defaultMinHeight  = "1000"
 )
 
-// get cmd to convert any bech32 address to an osmo prefix.
+// forceprune gets cmd to convert any bech32 address to an osmo prefix.
 func forceprune() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "forceprune",
@@ -94,6 +94,7 @@ func forceprune() *cobra.Command {
 	return cmd
 }
 
+// pruneBlockStoreAndGetHeights prunes blockstore and returns the startHeight and currentHeight.
 func pruneBlockStoreAndGetHeights(dbPath string, fullHeight int64) (
 	startHeight int64, currentHeight int64, err error,
 ) {
@@ -131,6 +132,7 @@ func pruneBlockStoreAndGetHeights(dbPath string, fullHeight int64) (
 	return startHeight, currentHeight, nil
 }
 
+// compactBlockStore compacts block storage.
 func compactBlockStore(dbPath string) (err error) {
 	compactOpts := opt.Options{
 		DisableSeeksCompaction: true,
@@ -151,6 +153,7 @@ func compactBlockStore(dbPath string) (err error) {
 	return nil
 }
 
+// forcepruneStateStore prunes and compacts state storage.
 func forcepruneStateStore(dbPath string, startHeight, currentHeight, minHeight, fullHeight int64) error {
 	opts := opt.Options{
 		DisableSeeksCompaction: true,

diff --git a/cmd/osmosisd/cmd/genesis.go b/cmd/osmosisd/cmd/genesis.go
@@ -34,6 +34,7 @@ import (
 )
 
 //nolint:ineffassign
+// PrepareGenesisCmd returns prepare-genesis cobra Command.
 func PrepareGenesisCmd(defaultNodeHome string, mbm module.BasicManager) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "prepare-genesis",

diff --git a/cmd/osmosisd/cmd/init.go b/cmd/osmosisd/cmd/init.go
@@ -44,6 +44,7 @@ type printInfo struct {
 	AppMessage json.RawMessage `json:"app_message" yaml:"app_message"`
 }
 
+// newPrintInfo initializes a printInfo struct.
 func newPrintInfo(moniker, chainID, nodeID, genTxsDir string, appMessage json.RawMessage) printInfo {
 	return printInfo{
 		Moniker:    moniker,
@@ -54,6 +55,7 @@ func newPrintInfo(moniker, chainID, nodeID, genTxsDir string, appMessage json.Ra
 	}
 }
 
+// displayInfo displays printInfo in JSON format.
 func displayInfo(info printInfo) error {
 	out, err := json.MarshalIndent(info, "", " ")
 	if err != nil {

diff --git a/cmd/osmosisd/cmd/root.go b/cmd/osmosisd/cmd/root.go
@@ -135,6 +135,7 @@ min-gas-price-for-high-gas-tx = ".0025"
 	return OsmosisAppTemplate, OsmosisAppCfg
 }
 
+// initRootCmd initializes root commands when creating a new root command for simd.
 func initRootCmd(rootCmd *cobra.Command, encodingConfig params.EncodingConfig) {
 	cfg := sdk.GetConfig()
 	cfg.Seal()
@@ -179,6 +180,7 @@ func addModuleInitFlags(startCmd *cobra.Command) {
 	wasm.AddModuleInitFlags(startCmd)
 }
 
+// queryCommand adds transaction and account querying commands.
 func queryCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:                        "query",
@@ -203,6 +205,7 @@ func queryCommand() *cobra.Command {
 	return cmd
 }
 
+// txCommand adds transaction signing, encoding / decoding, and broadcasting commands.
 func txCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:                        "tx",
@@ -229,6 +232,7 @@ func txCommand() *cobra.Command {
 	return cmd
 }
 
+// newApp initializes and returns a new Osmosis app.
 func newApp(logger log.Logger, db dbm.DB, traceStore io.Writer, appOpts servertypes.AppOptions) servertypes.Application {
 	var cache sdk.MultiStorePersistentCache
 
@@ -282,6 +286,7 @@ func newApp(logger log.Logger, db dbm.DB, traceStore io.Writer, appOpts serverty
 	)
 }
 
+// createOsmosisAppAndExport creates and exports the new Osmosis app, returns the state of the new Osmosis app for a genesis file.
 func createOsmosisAppAndExport(
 	logger log.Logger, db dbm.DB, traceStore io.Writer, height int64, forZeroHeight bool, jailWhiteList []string,
 	appOpts servertypes.AppOptions,

diff --git a/cmd/osmosisd/cmd/testnet.go b/cmd/osmosisd/cmd/testnet.go
@@ -45,7 +45,7 @@ var (
 	emptyMnemonic = ""
 )
 
-// get cmd to initialize all files for tendermint testnet and application.
+// testnetCmd gets the cmd to initialize all files for tendermint testnet and application.
 func testnetCmd(mbm module.BasicManager, genBalIterator banktypes.GenesisBalancesIterator) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "testnet",
@@ -105,7 +105,7 @@ Example:
 
 const nodeDirPerm = 0o755
 
-// Initialize the testnet.
+// InitTestnet initializes the testnet.
 func InitTestnet(
 	clientCtx client.Context,
 	cmd *cobra.Command,
@@ -270,6 +270,7 @@ func InitTestnet(
 	return nil
 }
 
+// initGenFiles initializes genesis files for testnet.
 func initGenFiles(
 	clientCtx client.Context, mbm module.BasicManager, genesisParams GenesisParams, chainID string,
 	genAccounts []authtypes.GenesisAccount, genBalances []banktypes.Balance,