update all client and primitives docs to include type name in docs

internal/client/api/backend.go

@@ -13,42 +13,41 @@ import (
 	"github.com/ChainSafe/gossamer/internal/primitives/storage"
 )
 
-// State of a new block.
+// NewBlockState is the state of a new block.
 type NewBlockState uint8
 
 const (
-	// Normal block.
+	// NewBlockStateNormal is a normal block.
 	NewBlockStateNormal NewBlockState = iota
-	// New best block.
+	// NewBlockStateBest is a new best block.
 	NewBlockStateBest
-	// Newly finalized block.
+	// NewBlockStateFinal is a newly finalized block.
 	NewBlockStateFinal
 )
 
+// IsBest returns true if equal to [NewBlockStateBest]
 func (nbs NewBlockState) IsBest() bool {
 	return nbs == NewBlockStateBest
 }
 
+// IsFinal returns true if equal to [NewBlockStateFinal]
 func (nbs NewBlockState) IsFinal() bool {
 	return nbs == NewBlockStateFinal
 }
 
-// Block insertion operation.
-//
-// Keeps hold of the inserted block state and data.
+// BlockImportOperation keeps hold of the inserted block state and data.
 type BlockImportOperation[
 	N runtime.Number,
 	H runtime.Hash,
 	Hasher runtime.Hasher[H],
 	Header runtime.Header[N, H],
 	E runtime.Extrinsic,
 ] interface {
-	// Returns pending state.
-	//
+	// State returns the pending state.
 	// Returns nil for backends with locally-unavailable state data.
 	State() (statemachine.Backend[H, Hasher], error)
 
-	// Set block data to the transaction.
+	// SetBlockData will set block data to the transaction.
 	SetBlockData(
 		header Header,
 		body []E,
@@ -57,35 +56,34 @@ type BlockImportOperation[
 		state NewBlockState,
 	) error
 
-	// Inject storage data into the database.
+	// UpdateDBStorage will inject storage data into the database.
 	UpdateDBStorage(update statemachine.BackendTransaction[H, Hasher]) error
 
-	// Set genesis state. If commit is false the state is saved in memory, but is not written
+	// SetGenesisState will set genesis state. If commit is false the state is saved in memory, but is not written
 	// to the database.
 	SetGenesisState(storage storage.Storage, commit bool, stateVersion storage.StateVersion) (H, error)
 
-	// Inject storage data into the database replacing any existing data.
+	// ResetStorage will inject storage data into the database replacing any existing data.
 	ResetStorage(storage storage.Storage, stateVersion storage.StateVersion) (H, error)
 
-	// Set storage changes.
+	// UpdateStorage will set storage changes.
 	UpdateStorage(update statemachine.StorageCollection, childUpdate statemachine.ChildStorageCollection) error
 
-	// Write offchain storage changes to the database.
+	// UpdateOffchainStorage will write offchain storage changes to the database.
 	UpdateOffchainStorage(offchainUpdate statemachine.OffchainChangesCollection) error
 
-	// Insert auxiliary keys.
-	//
+	// InsertAux will insert auxiliary keys.
 	// Values that are nil respresent the keys should be deleted.
 	InsertAux(ops AuxDataOperations) error
 
-	// Mark a block as finalized.
+	// MarkFinalized marks a block as finalized.
 	MarkFinalized(hash H, justification *runtime.Justification) error
 
-	// Mark a block as new head. If the block import changes the head and MarkHead is called with a different
-	// block hash, MarkHead will override the changed head as a result of the block import.
+	// MarkHead marks a block as the new head. If the block import changes the head and MarkHead is called with
+	// a different block hash, MarkHead will override the changed head as a result of the block import.
 	MarkHead(hash H) error
 
-	// Add a transaction index operation.
+	// UpdateTransactionIndex adds a transaction index operation.
 	UpdateTransactionIndex(index []statemachine.IndexOperation) error
 }
 
@@ -94,7 +92,7 @@ type KeyValue struct {
 	Value []byte
 }
 
-// Provides access to an auxiliary database.
+// AuxStore provides access to an auxiliary database.
 //
 // This is a simple global database not aware of forks. Can be used for storing auxiliary
 // information like total block weight/difficulty for fork resolution purposes as a common use
@@ -109,7 +107,7 @@ type AuxStore interface {
 	GetAux(key []byte) ([]byte, error)
 }
 
-// Client backend.
+// Backend is the client backend.
 //
 // Manages the data layer.
 //
@@ -138,51 +136,49 @@ type Backend[
 	Header runtime.Header[N, H],
 	E runtime.Extrinsic,
 ] interface {
-	// Insert auxiliary data into key-value store.
-	AuxStore
+	AuxStore // Insert auxiliary data into key-value store.
 
-	// Begin a new block insertion transaction with given parent block id.
-	//
+	// BeginOperation begins a new block insertion transaction with given parent block id.
 	// When constructing the genesis, this is called with all-zero hash.
 	BeginOperation() (BlockImportOperation[N, H, Hasher, Header, E], error)
 
-	// Note an operation to contain state transition.
+	// BeginStateOperation notes an operation to contain state transition.
 	BeginStateOperation(operation BlockImportOperation[N, H, Hasher, Header, E], block H) error
 
-	// Commit block insertion.
+	// CommitOperation will commit block insertion.
 	CommitOperation(transaction BlockImportOperation[N, H, Hasher, Header, E]) error
 
-	// Finalize block with given hash.
+	// FinalizeBlock will finalize block with given hash.
 	//
 	// This should only be called if the parent of the given block has been finalized.
 	FinalizeBlock(hash H, justification *runtime.Justification) error
 
-	// Append justification to the block with the given hash.
+	// AppendJustification appends justification to the block with the given hash.
 	//
 	// This should only be called for blocks that are already finalized.
 	AppendJustification(hash H, justification runtime.Justification) error
 
-	// Returns reference to blockchain backend.
+	// Blockchain returns reference to blockchain backend.
 	Blockchain() blockchain.Backend[H, N, Header, E]
 
-	// Returns a pointer to offchain storage.
+	// OffchainStorage returns a pointer to offchain storage.
 	OffchainStorage() offchain.OffchainStorage
 
-	// Pin the block to keep body, justification and state available after pruning.
+	// PinBlock pins the block to keep body, justification and state available after pruning.
 	// Number of pins are reference counted. Users need to make sure to perform
 	// one call to UnpinBlock per call to PinBlock.
 	PinBlock(hash H) error
 
 	// Unpin the block to allow pruning.
 	UnpinBlock(hash H)
 
-	// Returns true if state for given block is available.
+	// HaveStateAt returns true if state for given block is available.
 	HaveStateAt(hash H, number N) bool
 
-	// Returns state backend with post-state of given block.
+	// StateAt returns state backend with post-state of given block.
 	StateAt(hash H) (statemachine.Backend[H, Hasher], error)
 
-	// Attempts to revert the chain by n blocks. If revertFinalized is set it will attempt to
+	// Revert attempts to revert the chain by n blocks. If revertFinalized is set it will attempt to
 	// revert past any finalized block. This is unsafe and can potentially leave the node in an
 	// inconsistent state. All blocks higher than the best block are also reverted and not counting
 	// towards n.
@@ -191,21 +187,21 @@ type Backend[
 	// blocks that has been reverted.
 	Revert(n N, revertFinalized bool) (N, map[H]any, error)
 
-	// Discard non-best, unfinalized leaf block.
+	// RemoveLeafBlock discards non-best, unfinalized leaf block.
 	RemoveLeafBlock(hash H) error
 
-	// Gain access to the import lock around this backend.
+	// GetImportLock returns access to the import lock for this backend.
 	//
 	// NOTE: Backend isn't expected to acquire the lock by itself ever. Rather
 	// the using components should acquire and hold the lock whenever they do
 	// something that the import of a block would interfere with, e.g. importing
 	// a new block or calculating the best head.
 	GetImportLock() *sync.RWMutex
 
-	// Tells whether the backend requires full-sync mode.
+	// RequiresFullSync tells whether the backend requires full-sync mode.
 	RequiresFullSync() bool
 
-	// Returns current usage statistics.
+	// UsageInfo returns current usage statistics.
 	// TODO: implement UsageInfo if we require it
 	// UsageInfo() *UsageInfo
 }

internal/client/api/client.go

@@ -3,7 +3,7 @@
 
 package api
 
-// List of operations to be performed on storage aux data.
+// AuxDataOperation is a slice of operations to be performed on storage aux data.
 // Key is the encoded data key.
 // Value is the encoded optional data to write.
 // If Value is nil, the key and the associated data are deleted from storage.

internal/client/api/leaves.go

@@ -45,9 +45,8 @@ func (fo FinalizationOutcome[H, N]) Leaves() []H {
 	return leaves
 }
 
-// list of leaf hashes ordered by number (descending).
-// stored in memory for fast access.
-// this allows very fast checking and modification of active leaves.
+// LeafSet is the list of leaf hashes ordered by number (descending) stored in memory for fast access.
+// This allows very fast checking and modification of active leaves.
 type LeafSet[H comparable, N runtime.Number] struct {
 	storage btree.Map[N, []H]
 }

internal/client/api/utils/utils.go

@@ -8,18 +8,16 @@ import (
 	"github.com/ChainSafe/gossamer/internal/primitives/runtime"
 )
 
-// Hash and parent hash of a block
+// HashParent is the hash and parent hash of a block
 type HashParent[H runtime.Hash] struct {
 	Hash   H
 	Parent H
 }
 
-// Returns a function for checking block ancestry, the returned function will
-// return true if the given hash (second parameter) is a descendent of the
-// base (first parameter). If current is defined, it should
-// represent the current block hash and its parent hash. if current is given, the
-// function that is returned will assume that current.Hash isn't part of the local DB
-// yet, and all searches in the DB will instead reference the parent.
+// IsDescendantOf returns a function for checking block ancestry, the returned function will return true if the given
+// hash (second parameter) is a descendent of the base (first parameter). If current is defined, it should represent
+// the current block hash and its parent hash. if current is given, the function that is returned will assume that
+// current.Hash isn't part of the local DB yet, and all searches in the DB will instead reference the parent.
 func IsDescendantOf[H runtime.Hash, N runtime.Number, Header runtime.Header[N, H], E runtime.Extrinsic](
 	client blockchain.Backend[H, N, Header, E], current *HashParent[H],
 ) func(a H, b H) (bool, error) {

internal/client/consensus/grandpa/authorities.go

@@ -3,7 +3,7 @@
 
 package grandpa
 
-// generic representation of hash and number tuple
+// HashNumber is a generic representation of hash and number
 type HashNumber[H, N any] struct {
 	Hash   H
 	Number N

internal/client/consensus/grandpa/justification.go

@@ -22,14 +22,13 @@ var (
 	errBlockNotDescendentOfBase = errors.New("block not descendent of base")
 )
 
-// A GRANDPA justification for block finality, it includes a commit message and
-// an ancestry proof including all headers routing all precommit target blocks
-// to the commit target block. Due to the current voting strategy the precommit
-// targets should be the same as the commit target, since honest voters don't
-// vote past authority set change blocks.
+// GrandpaJustification is a GRANDPA justification for block finality, it includes a commit message and an ancestry
+// proof including all headers routing all precommit target blocks to the commit target block. Due to the current
+// voting strategy the precommit targets should be the same as the commit target, since honest voters don't vote past
+// authority set change blocks.
 //
-// This is meant to be stored in the db and passed around the network to other
-// nodes, and are used by syncing nodes to prove authority set handoffs.
+// This is meant to be stored in the db and passed around the network to other nodes, and are used by syncing nodes
+// to prove authority set handoffs.
 type GrandpaJustification[Hash runtime.Hash, N runtime.Number] struct {
 	// The GRANDPA justification for block finality.
 	Justification primitives.GrandpaJustification[Hash, N]