Merge pull request #15 from dipdup-io/GO-75-add-documentation-for-models

GO 75 add documentation for models

cmd/mempool/models/activate_account.go

@@ -3,8 +3,8 @@ package models
 // ActivateAccount -
 type ActivateAccount struct {
 	//nolint
-	tableName struct{} `pg:"activate_account"`
+	tableName struct{} `pg:"activate_account" comment:"activation operation - is used to activate accounts that were recommended allocations of tezos tokens for donations to the Tezos Foundation’s fundraiser."`
 	MempoolOperation
-	Pkh    string `json:"pkh"`
-	Secret string `json:"secret"`
+	Pkh    string `json:"pkh" comment:"Public key hash (Ed25519). Address to activate."`
+	Secret string `json:"secret" comment:"The secret key associated with the key, if available. /^([a-zA-Z0-9][a-zA-Z0-9])*$/"`
 }

cmd/mempool/models/ballot.go

@@ -3,10 +3,10 @@ package models
 // Ballot -
 type Ballot struct {
 	//nolint
-	tableName struct{} `pg:"ballots"`
+	tableName struct{} `pg:"ballots" comment:"ballot operation - is used to vote for a proposal in a given voting cycle."`
 	MempoolOperation
-	Period int64  `json:"period"`
-	Ballot string `json:"ballot"`
+	Period int64  `json:"period" comment:"Voting period index, starting from zero, for which the ballot was submitted."`
+	Ballot string `json:"ballot" comment:"Vote, given in the ballot (yay, nay, or pass)."`
 }
 
 // SetMempoolOperation -

cmd/mempool/models/database.go

@@ -34,6 +34,11 @@ func OpenDatabaseConnection(ctx context.Context, cfg config.Database, kinds ...s
 			return nil, err
 		}
 	}
+
+	if err := database.MakeComments(ctx, db, data...); err != nil {
+		return nil, err
+	}
+
 	db.DB().AddQueryHook(dbLogger{})
 
 	return db, nil

cmd/mempool/models/delegation.go

@@ -3,14 +3,14 @@ package models
 // Delegation -
 type Delegation struct {
 	//nolint
-	tableName struct{} `pg:"delegations"`
+	tableName struct{} `pg:"delegations" comment:"delegation operation - is used to delegate funds to a delegate (an implicit account registered as a baker)."`
 	MempoolOperation
-	Fee          int64  `json:"fee,string"`
-	Counter      int64  `json:"counter,string" pg:",pk"`
-	GasLimit     int64  `json:"gas_limit,string"`
-	StorageLimit int64  `json:"storage_limit,string"`
-	Delegate     string `json:",omitempty"`
-	Source       string `json:"source,omitempty" index:"delegation_source_idx"`
+	Fee          int64  `json:"fee,string" comment:"Fee to a baker, produced block, in which the operation was included."`
+	Counter      int64  `json:"counter,string" pg:",pk" comment:"An account nonce which is used to prevent operation replay."`
+	GasLimit     int64  `json:"gas_limit,string" comment:"A cap on the amount of gas a given operation can consume."`
+	StorageLimit int64  `json:"storage_limit,string" comment:"A cap on the amount of storage a given operation can consume."`
+	Delegate     string `json:",omitempty" comment:"Address of the delegate to which the operation was sent. null if there is no new delegate (an un-delegation operation)."`
+	Source       string `json:"source,omitempty" index:"delegation_source_idx" comment:"Address of the delegated account."`
 }
 
 // SetMempoolOperation -

cmd/mempool/models/double_baking.go

@@ -3,23 +3,23 @@ package models
 // DoubleBaking -
 type DoubleBaking struct {
 	//nolint
-	tableName struct{} `pg:"double_bakings"`
+	tableName struct{} `pg:"double_bakings" comment:"double_baking operation - is used by bakers to provide evidence of double baking (baking two different blocks at the same height) by a baker."`
 
 	MempoolOperation
 	Bh1 DoubleBakingInfo `json:"bh1" pg:"-"`
 	Bh2 DoubleBakingInfo `json:"bh2" pg:"-"`
 
-	Bh1Level            uint64 `json:"-" pg:"bh1_level"`
-	Bh1Proto            int64  `json:"-" pg:"bh1_proto"`
-	Bh1ValidationPass   int64  `json:"-" pg:"bh1_validation_pass"`
-	Bh1Priority         int64  `json:"-" pg:"bh1_priority"`
-	Bh1ProofOfWorkNonce string `json:"-" pg:"bh1_proof_of_work_nonce"`
+	Bh1Level            uint64 `json:"-" pg:"bh1_level" comment:"Height of the first block from the genesis."`
+	Bh1Proto            int64  `json:"-" pg:"bh1_proto" comment:"First block protocol code, representing a number of protocol changes since genesis (mod 256, but -1 for the genesis block)."`
+	Bh1ValidationPass   int64  `json:"-" pg:"bh1_validation_pass" comment:"First block number of endorsements (slots), included into the block."`
+	Bh1Priority         int64  `json:"-" pg:"bh1_priority" comment:"First block priority [DEPRECATED]."`
+	Bh1ProofOfWorkNonce string `json:"-" pg:"bh1_proof_of_work_nonce" comment:"First block proof of work nonce."`
 
-	Bh2Level            uint64 `json:"-" pg:"bh2_level"`
-	Bh2Proto            int64  `json:"-" pg:"bh2_proto"`
-	Bh2ValidationPass   int64  `json:"-" pg:"bh2_validation_pass"`
-	Bh2Priority         int64  `json:"-" pg:"bh2_priority"`
-	Bh2ProofOfWorkNonce string `json:"-" pg:"bh2_proof_of_work_nonce"`
+	Bh2Level            uint64 `json:"-" pg:"bh2_level" comment:"Height of the second block from the genesis."`
+	Bh2Proto            int64  `json:"-" pg:"bh2_proto" comment:"Second block protocol code, representing a number of protocol changes since genesis (mod 256, but -1 for the genesis block)."`
+	Bh2ValidationPass   int64  `json:"-" pg:"bh2_validation_pass" comment:"Second block number of endorsements (slots), included into the block."`
+	Bh2Priority         int64  `json:"-" pg:"bh2_priority" comment:"Second block priority [DEPRECATED]."`
+	Bh2ProofOfWorkNonce string `json:"-" pg:"bh2_proof_of_work_nonce" comment:"Second block proof of work nonce."`
 }
 
 // DoubleBakingInfo -

cmd/mempool/models/double_endorsing.go

@@ -3,13 +3,13 @@ package models
 // DoubleEndorsing -
 type DoubleEndorsing struct {
 	//nolint
-	tableName struct{} `pg:"double_endorsings"`
+	tableName struct{} `pg:"double_endorsings" comment:"double_endorsing operation - is used by bakers to provide evidence of double endorsement (endorsing two different blocks at the same block height) by a baker."`
 
 	MempoolOperation
-	Op1Kind  string `json:"-" pg:"op1_kind"`
-	Op1Level uint64 `json:"-" pg:"op1_level"`
-	Op2Kind  string `json:"-" pg:"op2_kind"`
-	Op2Level uint64 `json:"-" pg:"op2_level"`
+	Op1Kind  string `json:"-" pg:"op1_kind" comment:"Kind of the first operation."`
+	Op1Level uint64 `json:"-" pg:"op1_level" comment:"Height of the block from the genesis block, in which the first operation was included."`
+	Op2Kind  string `json:"-" pg:"op2_kind" comment:"Kind of the second operation."`
+	Op2Level uint64 `json:"-" pg:"op2_level" comment:"Height of the block from the genesis block, in which the second operation was included."`
 
 	Op1 struct {
 		Operations DoubleEndorsingOperations `json:"operations"`

cmd/mempool/models/double_preendorsing.go

@@ -6,10 +6,10 @@ type DoublePreendorsing struct {
 	tableName struct{} `pg:"double_preendorsings"`
 
 	MempoolOperation
-	Op1Kind  string `json:"-" pg:"op1_kind"`
-	Op1Level uint64 `json:"-" pg:"op1_level"`
-	Op2Kind  string `json:"-" pg:"op2_kind"`
-	Op2Level uint64 `json:"-" pg:"op2_level"`
+	Op1Kind  string `json:"-" pg:"op1_kind" comment:"Kind of the first operation."`
+	Op1Level uint64 `json:"-" pg:"op1_level" comment:"Height of the block from the genesis block, in which the first operation was included."`
+	Op2Kind  string `json:"-" pg:"op2_kind" comment:"Kind of the second operation."`
+	Op2Level uint64 `json:"-" pg:"op2_level" comment:"Height of the block from the genesis block, in which the second operation was included."`
 
 	Op1 struct {
 		Operations DoublePreendorsingOperations `json:"operations"`

cmd/mempool/models/drain_delegate.go

@@ -6,9 +6,9 @@ type DelegateDrain struct {
 	tableName struct{} `pg:"drain_delegate"`
 
 	MempoolOperation
-	ConsensusKey int64  `json:"consensus_key"`
-	Delegate     string `json:"delegate"`
-	Destination  string `json:"destination"`
+	ConsensusKey int64  `json:"consensus_key" comment:"Consensus key that was used to sign Drain."`
+	Delegate     string `json:"delegate" comment:"Address of the drained delegate."`
+	Destination  string `json:"destination" comment:"Address of the recipient account."`
 }
 
 // SetMempoolOperation -

cmd/mempool/models/endorsement.go

@@ -1,14 +1,14 @@
 package models
 
-import pg "github.com/go-pg/pg/v10"
+import "github.com/go-pg/pg/v10"
 
 // Endorsement -
 type Endorsement struct {
 	//nolint
-	tableName struct{} `pg:"endorsements"`
+	tableName struct{} `pg:"endorsements" comment:"endorsement is an operation, which specifies the head of the chain as seen by the endorser of a given slot. The endorser is randomly selected to be included in the block that extends the head of the chain as specified in this operation. A block with more endorsements improves the weight of the chain and increases the likelihood of that chain being the canonical one."`
 	MempoolOperation
-	Level uint64 `json:"level"`
-	Baker string `json:"-" index:"transaction_baker_idx"`
+	Level uint64 `json:"level" comment:"The height of the block from the genesis block, in which the operation was included."`
+	Baker string `json:"-" index:"transaction_baker_idx" comment:"Address of the baker who sent the operation."`
 }
 
 // EndorsementsWithoutBaker -

cmd/mempool/models/gas_stats.go

@@ -13,13 +13,13 @@ import (
 type GasStats struct {
 	//nolint
 	tableName      struct{} `pg:"gas_stats"`
-	Network        string   `pg:",pk" json:"network"`
-	Hash           string   `pg:",pk" json:"hash"`
-	TotalGasUsed   uint64   `pg:"total_gas_used" json:"total_gas_used"`
-	TotalFee       uint64   `pg:"total_fee" json:"total_fee"`
-	UpdatedAt      int64    `json:"updated_at"`
-	LevelInMempool uint64   `json:"level_in_mempool"`
-	LevelInChain   uint64   `json:"level_in_chain"`
+	Network        string   `pg:",pk" json:"network" comment:"Identifies belonging network."`
+	Hash           string   `pg:",pk" json:"hash" comment:"Hash of the operation."`
+	TotalGasUsed   uint64   `pg:"total_gas_used" json:"total_gas_used" comment:"Total amount of consumed gas."`
+	TotalFee       uint64   `pg:"total_fee" json:"total_fee" comment:"Total amount of fee."`
+	UpdatedAt      int64    `json:"updated_at" comment:"Date of last update in seconds since UNIX epoch."`
+	LevelInMempool uint64   `json:"level_in_mempool" comment:"Level of the block at which the statistics has been calculated in mempool."`
+	LevelInChain   uint64   `json:"level_in_chain" comment:"Level of the block at which the statistics has been calculated in chain."`
 }
 
 // BeforeInsert -

cmd/mempool/models/mempool_operation.go

@@ -36,19 +36,19 @@ type ChangableMempoolOperation interface {
 
 // MempoolOperation -
 type MempoolOperation struct {
-	CreatedAt       int64   `json:"-"`
-	UpdatedAt       int64   `json:"-"`
-	Network         string  `json:"network" pg:",pk"`
-	Hash            string  `json:"hash" pg:",pk"`
-	Branch          string  `json:"branch"`
-	Status          string  `json:"status"`
-	Kind            string  `json:"kind"`
-	Signature       string  `json:"signature"`
-	Protocol        string  `json:"protocol"`
-	Level           uint64  `json:"level"`
-	Errors          JSONB   `json:"errors,omitempty" pg:"type:jsonb"`
-	ExpirationLevel *uint64 `json:"expiration_level"`
-	Raw             JSONB   `json:"raw,omitempty" pg:"type:jsonb"`
+	CreatedAt       int64   `json:"-" comment:"Date of creation in seconds since UNIX epoch."`
+	UpdatedAt       int64   `json:"-" comment:"Date of last update in seconds since UNIX epoch."`
+	Network         string  `json:"network" pg:",pk" comment:"Identifies belonging network."`
+	Hash            string  `json:"hash" pg:",pk" comment:"Hash of the operation."`
+	Branch          string  `json:"branch" comment:"Hash of the block, in which the operation was included."`
+	Status          string  `json:"status" comment:"Status of the operation."`
+	Kind            string  `json:"kind" comment:"Type of the operation."`
+	Signature       string  `json:"signature" comment:"Signature of the operation."`
+	Protocol        string  `json:"protocol" comment:"Hash of the protocol, in which the operation was included in mempool."`
+	Level           uint64  `json:"level" comment:"The height of the block from the genesis block, in which the operation was included."`
+	Errors          JSONB   `json:"errors,omitempty" pg:"type:jsonb" comment:"Errors with the operation processing if any."`
+	ExpirationLevel *uint64 `json:"expiration_level" comment:"Datetime of block expiration in which the operation was included in seconds since UNIX epoch."`
+	Raw             JSONB   `json:"raw,omitempty" pg:"type:jsonb" comment:"Raw JSON object of the operation."`
 }
 
 // BeforeInsert -

cmd/mempool/models/nonce_revelation.go

@@ -3,10 +3,10 @@ package models
 // NonceRevelation -
 type NonceRevelation struct {
 	//nolint
-	tableName struct{} `pg:"nonce_revelations"`
+	tableName struct{} `pg:"nonce_revelations" comment:"nonce_revelation operation - are used by the blockchain to create randomness."`
 	MempoolOperation
-	Level int    `json:"level"`
-	Nonce string `json:"nonce"`
+	Level int    `json:"level" comment:"The height of the block from the genesis block, in which the operation was included."`
+	Nonce string `json:"nonce" comment:"Seed nonce hex."`
 }
 
 // SetMempoolOperation -

cmd/mempool/models/origination.go

@@ -7,20 +7,20 @@ import (
 // Origination -
 type Origination struct {
 	//nolint
-	tableName struct{} `pg:"originations"`
+	tableName struct{} `pg:"originations" comment:"origination - deployment / contract creation operation."`
 	MempoolOperation
-	Fee          int64  `json:"fee,string"`
-	Counter      int64  `json:"counter,string" pg:",pk" `
-	GasLimit     int64  `json:"gas_limit,string"`
-	StorageLimit int64  `json:"storage_limit,string"`
-	Balance      string `json:"balance"`
-	Delegate     string `json:",omitempty"`
-	Source       string `json:"source,omitempty" index:"origination_source_idx"`
+	Fee          int64  `json:"fee,string" comment:"Fee to the baker, produced block, in which the operation was included (micro tez)."`
+	Counter      int64  `json:"counter,string" pg:",pk" comment:"An account nonce which is used to prevent operation replay."`
+	GasLimit     int64  `json:"gas_limit,string" comment:"A cap on the amount of gas a given operation can consume."`
+	StorageLimit int64  `json:"storage_limit,string" comment:"A cap on the amount of storage a given operation can consume."`
+	Balance      string `json:"balance" comment:"The contract origination balance (micro tez)."`
+	Delegate     string `json:",omitempty" comment:"Address of the baker (delegate), which was marked as a delegate in the operation."`
+	Source       string `json:"source,omitempty" index:"origination_source_idx" comment:"Address of the account who has sent the operation."`
 	Script       struct {
 		Storage json.RawMessage `json:"storage"`
 	} `json:"script" pg:"-"`
 
-	Storage JSONB `json:"-" pg:"type:jsonb"`
+	Storage JSONB `json:"-" pg:"type:jsonb" comment:"Initial contract storage value converted to human-readable JSON."`
 }
 
 // Fill -

cmd/mempool/models/proposal.go

@@ -3,8 +3,8 @@ package models
 // Proposal -
 type Proposal struct {
 	//nolint
-	tableName struct{} `pg:"proposals"`
+	tableName struct{} `pg:"proposals" comment:"proposal operation - is used by bakers (delegates) to submit and/or upvote proposals to amend the protocol."`
 	MempoolOperation
-	Period    int64  `json:"period"`
-	Proposals string `json:"proposal" pg:"proposals"`
+	Period    int64  `json:"period" comment:"Voting period index (starting from zero) for which the proposal was submitted (upvoted)."`
+	Proposals string `json:"proposal" pg:"proposals" comment:"Information about the submitted (upvoted) proposal."`
 }

cmd/mempool/models/register_global_constant.go

@@ -3,14 +3,14 @@ package models
 // RegisterGlobalConstant -
 type RegisterGlobalConstant struct {
 	//nolint
-	tableName struct{} `pg:"register_global_constant"`
+	tableName struct{} `pg:"register_global_constant" comment:"register_constant operation - is used to register a global constant - Micheline expression that can be reused by multiple smart contracts."`
 	MempoolOperation
-	Source       string `json:"source"`
-	Fee          string `json:"fee"`
-	Counter      string `json:"counter"`
-	GasLimit     string `json:"gas_limit"`
-	StorageLimit string `json:"storage_limit"`
-	Value        JSONB  `json:"value"  pg:"value,type:jsonb"`
+	Source       string `json:"source" comment:"Address of the account who has sent the operation."`
+	Fee          string `json:"fee" comment:"Fee to the baker, produced block, in which the operation was included (micro tez)."`
+	Counter      string `json:"counter" comment:"An account nonce which is used to prevent operation replay."`
+	GasLimit     string `json:"gas_limit" comment:"A cap on the amount of gas a given operation can consume."`
+	StorageLimit string `json:"storage_limit" comment:"A cap on the amount of storage a given operation can consume."`
+	Value        JSONB  `json:"value"  pg:"value,type:jsonb" comment:"Constant value (Micheline JSON)."`
 }
 
 // SetMempoolOperation -

cmd/mempool/models/reveal.go

@@ -3,12 +3,12 @@ package models
 // Reveal -
 type Reveal struct {
 	//nolint
-	tableName struct{} `pg:"reveals"`
+	tableName struct{} `pg:"reveals" comment:"reveal operation - is used to reveal the public key associated with an account."`
 	MempoolOperation
-	Source       string `json:"source" index:"reveal_source_idx"`
-	Fee          int64  `json:"fee,string"`
-	Counter      int64  `json:"counter,string" pg:",pk" `
-	GasLimit     int64  `json:"gas_limit,string"`
-	StorageLimit int64  `json:"storage_limit,string"`
-	PublicKey    string `json:"public_key"`
+	Source       string `json:"source" index:"reveal_source_idx" comment:"Address of the account who has sent the operation."`
+	Fee          int64  `json:"fee,string" comment:"Fee to the baker, produced block, in which the operation was included (micro tez)."`
+	Counter      int64  `json:"counter,string" pg:",pk" comment:"An account nonce which is used to prevent operation replay."`
+	GasLimit     int64  `json:"gas_limit,string" comment:"A cap on the amount of gas a given operation can consume."`
+	StorageLimit int64  `json:"storage_limit,string" comment:"A cap on the amount of storage a given operation can consume."`
+	PublicKey    string `json:"public_key" comment:"Public key of source address."`
 }

cmd/mempool/models/set_deposits_limit.go

@@ -6,12 +6,12 @@ type SetDepositsLimit struct {
 	tableName struct{} `pg:"set_deposits_limit"`
 
 	MempoolOperation
-	Fee          int64   `json:"fee,string"`
-	Counter      int64   `pg:",pk" json:"counter,string"`
-	GasLimit     int64   `json:"gas_limit,string"`
-	StorageLimit int64   `json:"storage_limit,string"`
-	Source       string  `json:"source,omitempty" index:"set_deposits_limit_source_idx"`
-	Limit        *string `json:"limit,omitempty"`
+	Fee          int64   `json:"fee,string" comment:"Fee to the baker, produced block, in which the operation was included (micro tez)."`
+	Counter      int64   `pg:",pk" json:"counter,string" comment:"An account nonce which is used to prevent operation replay."`
+	GasLimit     int64   `json:"gas_limit,string" comment:"A cap on the amount of gas a given operation can consume."`
+	StorageLimit int64   `json:"storage_limit,string" comment:"A cap on the amount of storage a given operation can consume."`
+	Source       string  `json:"source,omitempty" index:"set_deposits_limit_source_idx" comment:"Address of the account who has sent the operation."`
+	Limit        *string `json:"limit,omitempty" comment:"Frozen deposits limit (mutez), or null if no limit."`
 }
 
 // SetMempoolOperation -

cmd/mempool/models/sr_add_message.go

@@ -6,12 +6,12 @@ type SmartRollupAddMessage struct {
 	tableName struct{} `pg:"sr_add_messages"`
 
 	MempoolOperation
-	Fee          int64    `json:"fee,string"`
-	Counter      int64    `pg:",pk" json:"counter,string"`
-	GasLimit     int64    `json:"gas_limit,string"`
-	StorageLimit int64    `json:"storage_limit,string"`
-	Source       string   `json:"source,omitempty" index:"set_deposits_limit_source_idx"`
-	Message      []string `json:"message"`
+	Fee          int64    `json:"fee,string" comment:"Fee to the baker, produced block, in which the operation was included (micro tez)."`
+	Counter      int64    `pg:",pk" json:"counter,string" comment:"An account nonce which is used to prevent operation replay."`
+	GasLimit     int64    `json:"gas_limit,string" comment:"A cap on the amount of gas a given operation can consume."`
+	StorageLimit int64    `json:"storage_limit,string" comment:"A cap on the amount of storage a given operation can consume."`
+	Source       string   `json:"source,omitempty" index:"set_deposits_limit_source_idx" comment:"Address of the account who has sent the operation."`
+	Message      []string `json:"message" comment:"Messages added to the smart rollup inbox (Array of hex strings)."`
 }
 
 // SetMempoolOperation -