chore: lint: enable method godoc linting

.golangci.yml

@@ -37,7 +37,7 @@ issues:
     - "^blank-imports: a blank import should be only in a main or test package, or have a comment justifying it"
     - "^dot-imports: should not use dot imports"
     - "^exported: (func|type) name will be used as [^\\s]+ by other packages, and that stutters; consider calling this \\w+"
-    - "^exported: comment on exported (const|function|method|type|var) [^\\s]+ should be of the form \"\\w+ ...\""
+    - "^exported: comment on exported (const|function|type|var) [^\\s]+ should be of the form \"\\w+ ...\""
     - "^exported: exported (const|function|method|type|var) [^\\s]+ should have comment (\\(or a comment on this block\\) )?or be unexported"
     - "^indent-error-flow: if block ends with a return statement, so drop this else and outdent its block \\(move short variable declaration to its own line if necessary\\)"
     - "^package-comments: package comment should be of the form \"Package \\w+ ...\""

blockstore/autobatch.go

@@ -149,7 +149,7 @@ func (bs *AutobatchBlockstore) doFlush(ctx context.Context, retryOnly bool) erro
 	return bs.flushErr
 }
 
-// caller must NOT hold stateLock
+// Flush caller must NOT hold stateLock
 func (bs *AutobatchBlockstore) Flush(ctx context.Context) error {
 	return bs.doFlush(ctx, false)
 }

blockstore/badger/blockstore.go

@@ -986,7 +986,8 @@ func (b *Blockstore) AllKeysChan(ctx context.Context) (<-chan cid.Cid, error) {
 	return ch, nil
 }
 
-// Implementation of BlockstoreIterator interface
+// Implementation of BlockstoreIterator interface ------------------------------
+
 func (b *Blockstore) ForEachKey(f func(cid.Cid) error) error {
 	if err := b.access(); err != nil {
 		return err
@@ -1092,7 +1093,7 @@ func (b *Blockstore) StorageKey(dst []byte, cid cid.Cid) []byte {
 	return dst[:reqsize]
 }
 
-// this method is added for lotus-shed needs
+// DB is added for lotus-shed needs
 // WARNING: THIS IS COMPLETELY UNSAFE; DONT USE THIS IN PRODUCTION CODE
 func (b *Blockstore) DB() *badger.DB {
 	return b.db

blockstore/net_serve.go

@@ -20,6 +20,7 @@ type NetworkStoreHandler struct {
 }
 
 // NOTE: This code isn't yet hardened to accept untrusted input. See TODOs here and in net.go
+
 func HandleNetBstoreStream(ctx context.Context, bs Blockstore, mss msgio.ReadWriteCloser) *NetworkStoreHandler {
 	ns := &NetworkStoreHandler{
 		msgStream: mss,

blockstore/splitstore/splitstore.go

@@ -297,7 +297,8 @@ func Open(path string, ds dstore.Datastore, hot, cold bstore.Blockstore, cfg *Co
 	return ss, nil
 }
 
-// Blockstore interface
+// Blockstore interface --------------------------------------------------------
+
 func (s *SplitStore) DeleteBlock(_ context.Context, _ cid.Cid) error {
 	// afaict we don't seem to be using this method, so it's not implemented
 	return errors.New("DeleteBlock not implemented on SplitStore; don't do this Luke!") //nolint
@@ -686,7 +687,7 @@ func (s *SplitStore) isWarm() bool {
 	return s.warmupEpoch.Load() > 0
 }
 
-// State tracking
+// Start state tracking
 func (s *SplitStore) Start(chain ChainAccessor, us stmgr.UpgradeSchedule) error {
 	s.chain = chain
 	curTs := chain.GetHeaviestTipSet()

blockstore/splitstore/splitstore_check.go

@@ -15,7 +15,7 @@ import (
 	"github.com/filecoin-project/lotus/chain/types"
 )
 
-// performs an asynchronous health-check on the splitstore; results are appended to
+// Check performs an asynchronous health-check on the splitstore; results are appended to
 // <splitstore-path>/check.txt
 func (s *SplitStore) Check() error {
 	s.headChangeMx.Lock()
@@ -141,7 +141,7 @@ func (s *SplitStore) doCheck(curTs *types.TipSet) error {
 	return nil
 }
 
-// provides some basic information about the splitstore
+// Info provides some basic information about the splitstore
 func (s *SplitStore) Info() map[string]interface{} {
 	info := make(map[string]interface{})
 	info["base epoch"] = s.baseEpoch

chain/exchange/protocol_encoding.go

@@ -22,7 +22,7 @@ type CompactedMessagesCBOR struct {
 	SecpkIncludes []messageIndices
 }
 
-// Unmarshal into the "decoding" struct, then copy into the actual struct.
+// UnmarshalCBOR unmarshals into the "decoding" struct, then copies into the actual struct.
 func (t *CompactedMessages) UnmarshalCBOR(r io.Reader) (err error) {
 	var c CompactedMessagesCBOR
 	if err := c.UnmarshalCBOR(r); err != nil {
@@ -41,7 +41,7 @@ func (t *CompactedMessages) UnmarshalCBOR(r io.Reader) (err error) {
 	return nil
 }
 
-// Copy into the encoding struct, then marshal.
+// MarshalCBOR copies into the encoding struct, then marshals.
 func (t *CompactedMessages) MarshalCBOR(w io.Writer) error {
 	if t == nil {
 		_, err := w.Write(cbg.CborNull)

chain/market/fundmanager.go

@@ -121,7 +121,7 @@ func (fm *FundManager) Reserve(ctx context.Context, wallet, addr address.Address
 	return fm.getFundedAddress(addr).reserve(ctx, wallet, amt)
 }
 
-// Subtract from `reserved`.
+// Release subtracts from `reserved`.
 func (fm *FundManager) Release(addr address.Address, amt abi.TokenAmount) error {
 	return fm.getFundedAddress(addr).release(amt)
 }

chain/messagepool/messagepool.go

@@ -1137,7 +1137,7 @@ func (mp *MessagePool) getStateBalance(ctx context.Context, addr address.Address
 	return act.Balance, nil
 }
 
-// this method is provided for the gateway to push messages.
+// PushUntrusted is provided for the gateway to push messages.
 // differences from Push:
 //   - strict checks are enabled
 //   - extra strict add checks are used when adding the messages to the msgSet

chain/stmgr/execute.go

@@ -16,7 +16,8 @@ func (sm *StateManager) TipSetState(ctx context.Context, ts *types.TipSet) (st c
 	return sm.tipSetState(ctx, ts, false)
 }
 
-// Recompute the tipset state without trying to lookup a pre-computed result in the chainstore.
+// RecomputeTipSetState recomputes the tipset state without trying to lookup a pre-computed result
+// in the chainstore.
 // Useful if we know that our local chain-state isn't complete (e.g., we've discarded the events).
 func (sm *StateManager) RecomputeTipSetState(ctx context.Context, ts *types.TipSet) (st cid.Cid, rec cid.Cid, err error) {
 	return sm.tipSetState(ctx, ts, true)

chain/stmgr/forks.go

@@ -224,9 +224,9 @@ func (sm *StateManager) HandleStateForks(ctx context.Context, root cid.Cid, heig
 	return retCid, nil
 }
 
-// Returns true executing tipsets between the specified heights would trigger an expensive
-// migration. NOTE: migrations occurring _at_ the target height are not included, as they're
-// executed _after_ the target height.
+// HasExpensiveForkBetween returns true where executing tipsets between the specified heights would
+// trigger an expensive migration. NOTE: migrations occurring _at_ the target height are not
+// included, as they're executed _after_ the target height.
 func (sm *StateManager) HasExpensiveForkBetween(parent, height abi.ChainEpoch) bool {
 	for h := parent; h < height; h++ {
 		if _, ok := sm.expensiveUpgrades[h]; ok {

chain/types/ethtypes/eth_types.go

@@ -483,7 +483,7 @@ func (h EthHash) String() string {
 	return "0x" + hex.EncodeToString(h[:])
 }
 
-// Should ONLY be used for blocks and Filecoin messages. Eth transactions expect a different hashing scheme.
+// ToCid should ONLY be used for blocks and Filecoin messages. Eth transactions expect a different hashing scheme.
 func (h EthHash) ToCid() cid.Cid {
 	// err is always nil
 	mh, _ := multihash.EncodeName(h[:], "blake2b-256")

chain/types/tipset_key.go

@@ -81,7 +81,7 @@ func (k TipSetKey) String() string {
 	return b.String()
 }
 
-// Bytes() returns a binary representation of the key.
+// Bytes returns a binary representation of the key.
 func (k TipSetKey) Bytes() []byte {
 	return []byte(k.value)
 }

chain/vm/vm.go

@@ -684,8 +684,8 @@ func (vm *LegacyVM) Flush(ctx context.Context) (cid.Cid, error) {
 	return root, nil
 }
 
-// Get the buffered blockstore associated with the LegacyVM. This includes any temporary blocks produced
-// during this LegacyVM's execution.
+// ActorStore gets the buffered blockstore associated with the LegacyVM. This includes any temporary
+// blocks produced during this LegacyVM's execution.
 func (vm *LegacyVM) ActorStore(ctx context.Context) adt.Store {
 	return adt.WrapStore(ctx, vm.cst)
 }

cmd/lotus-sim/simulation/stages/funding_stage.go

@@ -53,7 +53,7 @@ func (fs *FundingStage) Fund(bb *blockbuilder.BlockBuilder, target address.Addre
 	return fs.fund(bb, target, 0)
 }
 
-// sendAndFund "packs" the given message, funding the actor if necessary. It:
+// SendAndFund "packs" the given message, funding the actor if necessary. It:
 //
 //  1. Tries to send the given message.
 //  2. If that fails, it checks to see if the exit code was ErrInsufficientFunds.

cmd/lotus-sim/simulation/stages/provecommit_stage.go

@@ -54,7 +54,7 @@ func (stage *ProveCommitStage) EnqueueProveCommit(
 	return stage.commitQueue.enqueueProveCommit(minerAddr, preCommitEpoch, info)
 }
 
-// packProveCommits packs all prove-commits for all "ready to be proven" sectors until it fills the
+// PackMessages packs all prove-commits for all "ready to be proven" sectors until it fills the
 // block or runs out.
 func (stage *ProveCommitStage) PackMessages(ctx context.Context, bb *blockbuilder.BlockBuilder) (_err error) {
 	if !stage.initialized {

cmd/lotus-sim/simulation/stages/windowpost_stage.go

@@ -41,7 +41,7 @@ func (*WindowPoStStage) Name() string {
 	return "window-post"
 }
 
-// packWindowPoSts packs window posts until either the block is full or all healty sectors
+// PackMessages packs window posts until either the block is full or all healty sectors
 // have been proven. It does not recover sectors.
 func (stage *WindowPoStStage) PackMessages(ctx context.Context, bb *blockbuilder.BlockBuilder) (_err error) {
 	// Push any new window posts into the queue.

itests/kit/blockminer.go

@@ -204,8 +204,9 @@ func (bm *BlockMiner) WatchMinerForPost(minerAddr address.Address) {
 	bm.postWatchMinersLk.Unlock()
 }
 
-// Like MineBlocks but refuses to mine until the window post scheduler has wdpost messages in the mempool
-// and everything shuts down if a post fails.  It also enforces that every block mined succeeds
+// MineBlocksMustPost is like MineBlocks but refuses to mine until the window post scheduler has
+// wdpost messages in the mempool and everything shuts down if a post fails.  It also enforces that
+// every block mined succeeds
 func (bm *BlockMiner) MineBlocksMustPost(ctx context.Context, blocktime time.Duration) {
 	time.Sleep(time.Second)
 

itests/kit/ensemble.go

@@ -222,7 +222,7 @@ func (n *Ensemble) FullNode(full *TestFullNode, opts ...NodeOpt) *Ensemble {
 	return n
 }
 
-// Miner enrolls a new miner, using the provided full node for chain
+// MinerEnroll enrolls a new miner, using the provided full node for chain
 // interactions.
 func (n *Ensemble) MinerEnroll(minerNode *TestMiner, full *TestFullNode, opts ...NodeOpt) *Ensemble {
 	require.NotNil(n.t, full, "full node required when instantiating miner")

itests/kit/evm.go

@@ -44,7 +44,7 @@ func (f *TestFullNode) EVM() *EVM {
 	return &EVM{f}
 }
 
-// SignLegacyHomesteadTransaction signs a legacy Homstead Ethereum transaction in place with the supplied private key.
+// SignLegacyEIP155Transaction signs a legacy Homstead Ethereum transaction in place with the supplied private key.
 func (e *EVM) SignLegacyEIP155Transaction(tx *ethtypes.EthLegacy155TxArgs, privKey []byte, chainID big.Int) {
 	preimage, err := tx.ToRlpUnsignedMsg()
 	require.NoError(e.t, err)
@@ -291,8 +291,8 @@ func (e *EVM) ComputeContractAddress(deployer ethtypes.EthAddress, nonce uint64)
 	return *(*ethtypes.EthAddress)(hasher.Sum(nil)[12:])
 }
 
-// return eth block from a wait return
-// this necessarily goes back one parent in the chain because wait is one block ahead of execution
+// GetEthBlockFromWait returns and eth block from a wait return.
+// This necessarily goes back one parent in the chain because wait is one block ahead of execution.
 func (e *EVM) GetEthBlockFromWait(ctx context.Context, wait *api.MsgLookup) ethtypes.EthBlock {
 	c, err := wait.TipSet.Cid()
 	require.NoError(e.t, err)

itests/kit/node_full.go

@@ -98,8 +98,8 @@ func (f *TestFullNode) WaitTillChain(ctx context.Context, pred ChainPredicate) *
 	return nil
 }
 
-// WaitTillChain waits until a specified chain condition is met. It returns
-// the first tipset where the condition is met.
+// WaitTillChainOrError waits until a specified chain condition is met. It returns
+// the first tipset where the condition is met. In the case of an error it will return the error.
 func (f *TestFullNode) WaitTillChainOrError(ctx context.Context, pred ChainPredicate) (*types.TipSet, error) {
 	ctx, cancel := context.WithCancel(ctx)
 	defer cancel()

lib/backupds/datastore.go

@@ -50,7 +50,7 @@ func Wrap(child datastore.Batching, logdir string) (*Datastore, error) {
 	return ds, nil
 }
 
-// Writes a datastore dump into the provided writer as
+// Backup writes a datastore dump into the provided writer as
 // [array(*) of [key, value] tuples, checksum]
 func (d *Datastore) Backup(ctx context.Context, out io.Writer) error {
 	scratch := make([]byte, 9)

node/impl/full/multisig.go

@@ -38,9 +38,9 @@ func (a *MsigAPI) messageBuilder(ctx context.Context, from address.Address) (mul
 	return multisig.Message(av, from), nil
 }
 
-// TODO: remove gp (gasPrice) from arguments
-// TODO: Add "vesting start" to arguments.
 func (a *MsigAPI) MsigCreate(ctx context.Context, req uint64, addrs []address.Address, duration abi.ChainEpoch, val types.BigInt, src address.Address, gp types.BigInt) (*api.MessagePrototype, error) {
+	// TODO: remove gp (gasPrice) from arguments
+	// TODO: Add "vesting start" to arguments.
 
 	mb, err := a.messageBuilder(ctx, src)
 	if err != nil {

node/impl/full/state.go

@@ -577,6 +577,7 @@ func (a *StateAPI) StateEncodeParams(ctx context.Context, toActCode cid.Cid, met
 }
 
 // This is on StateAPI because miner.Miner requires this, and MinerAPI requires miner.Miner
+
 func (a *StateAPI) MinerGetBaseInfo(ctx context.Context, maddr address.Address, epoch abi.ChainEpoch, tsk types.TipSetKey) (*api.MiningBaseInfo, error) {
 	// XXX: Gets the state by computing the tipset state, instead of looking at the parent.
 	return stmgr.MinerGetBaseInfo(ctx, a.StateManager, a.Beacon, tsk, epoch, maddr, a.ProofVerifier)
@@ -1175,7 +1176,7 @@ func (a *StateAPI) StateSectorPreCommitInfo(ctx context.Context, maddr address.A
 	return pci, err
 }
 
-// Returns nil, nil if sector is not found
+// StateSectorGetInfo returns nil, nil if sector is not found
 func (m *StateModule) StateSectorGetInfo(ctx context.Context, maddr address.Address, n abi.SectorNumber, tsk types.TipSetKey) (*miner.SectorOnChainInfo, error) {
 	ts, err := m.Chain.GetTipSetFromKey(ctx, tsk)
 	if err != nil {

node/impl/storminer.go

@@ -251,7 +251,7 @@ func (sm *StorageMinerAPI) SectorUnseal(ctx context.Context, sectorNum abi.Secto
 	return nil
 }
 
-// List all staged sectors
+// SectorsList lists all staged sectors
 func (sm *StorageMinerAPI) SectorsList(context.Context) ([]abi.SectorNumber, error) {
 	sectors, err := sm.Miner.ListSectors()
 	if err != nil {
@@ -297,8 +297,8 @@ func (sm *StorageMinerAPI) SectorsListInStates(ctx context.Context, states []api
 	return sns, nil
 }
 
-// Use SectorsSummary from stats (prometheus) for faster result
 func (sm *StorageMinerAPI) SectorsSummary(ctx context.Context) (map[api.SectorState]int, error) {
+	// Use SectorsSummary from stats (prometheus) for faster result
 	return sm.Miner.SectorsSummary(ctx), nil
 }
 

node/repo/fsrepo.go

@@ -347,7 +347,7 @@ func (fsr *FsRepo) Lock(repoType RepoType) (LockedRepo, error) {
 	}, nil
 }
 
-// Like Lock, except datastores will work in read-only mode
+// LockRO is like Lock, except datastores will work in read-only mode
 func (fsr *FsRepo) LockRO(repoType RepoType) (LockedRepo, error) {
 	lr, err := fsr.Lock(repoType)
 	if err != nil {

paychmgr/manager.go

@@ -332,8 +332,9 @@ func (pm *Manager) trackInboundChannel(ctx context.Context, ch address.Address)
 	return pm.store.TrackChannel(ctx, stateCi)
 }
 
-// TODO: secret vs proof doesn't make sense, there is only one, not two
 func (pm *Manager) SubmitVoucher(ctx context.Context, ch address.Address, sv *paychtypes.SignedVoucher, secret []byte, proof []byte) (cid.Cid, error) {
+	// TODO: secret vs proof doesn't make sense, there is only one, not two
+
 	if len(proof) > 0 {
 		return cid.Undef, errProofNotSupported
 	}

storage/pipeline/commit_batch.go

@@ -755,7 +755,7 @@ func (b *CommitBatcher) processSingleV1(cfg sealiface.Config, mi api.MinerInfo,
 	return mcid, nil
 }
 
-// register commit, wait for batch message, return message CID
+// AddCommit registers a commit, waits for batch message, returns message CID
 func (b *CommitBatcher) AddCommit(ctx context.Context, s SectorInfo, in AggregateInput) (res sealiface.CommitBatchRes, err error) {
 	sn := s.SectorNumber
 

storage/pipeline/precommit_batch.go

@@ -323,7 +323,7 @@ func (b *PreCommitBatcher) processBatch(cfg sealiface.Config, tsk types.TipSetKe
 	return b.processPreCommitBatch(cfg, bf, pcEntries, nv)
 }
 
-// register PreCommit, wait for batch message, return message CID
+// AddPreCommit registers PreCommit, waits for batch message, returns message CID
 func (b *PreCommitBatcher) AddPreCommit(ctx context.Context, s SectorInfo, deposit abi.TokenAmount, in *miner.SectorPreCommitInfo) (res sealiface.PreCommitBatchRes, err error) {
 	ts, err := b.api.ChainHead(b.mctx)
 	if err != nil {

storage/pipeline/terminate_batch.go

@@ -257,7 +257,7 @@ func (b *TerminateBatcher) processBatch(notif, after bool) (*cid.Cid, error) {
 	return &mcid, nil
 }
 
-// register termination, wait for batch message, return message CID
+// AddTermination registers termination, waits for batch message, returns message CID
 // can return cid.Undef,true if the sector is already terminated on-chain
 func (b *TerminateBatcher) AddTermination(ctx context.Context, s abi.SectorID) (mcid cid.Cid, terminated bool, err error) {
 	maddr, err := address.NewIDAddress(uint64(s.Miner))

storage/pipeline/types.go

@@ -241,7 +241,7 @@ func (sp *SafeSectorPiece) DealInfo() UniversalPieceInfo {
 	return sp.real.DealInfo
 }
 
-// cbor passthrough
+// UnmarshalCBOR is a cbor passthrough
 func (sp *SafeSectorPiece) UnmarshalCBOR(r io.Reader) (err error) {
 	return sp.real.UnmarshalCBOR(r)
 }
@@ -250,7 +250,7 @@ func (sp *SafeSectorPiece) MarshalCBOR(w io.Writer) error {
 	return sp.real.MarshalCBOR(w)
 }
 
-// json passthrough
+// UnmarshalJSON is a json passthrough
 func (sp *SafeSectorPiece) UnmarshalJSON(b []byte) error {
 	return json.Unmarshal(b, &sp.real)
 }

storage/sealer/sched_resources.go

@@ -115,7 +115,7 @@ func (a *ActiveResources) hasWorkWaiting() bool {
 	return a.waiting > 0
 }
 
-// add task resources to ActiveResources and return utilization difference
+// Add task resources to ActiveResources and return utilization difference
 func (a *ActiveResources) Add(schedID uuid.UUID, tt sealtasks.SealTaskType, wr storiface.WorkerResources, r storiface.Resources) float64 {
 	startUtil := a.utilization(wr)
 

storage/sealer/storiface/filetype.go

@@ -227,7 +227,7 @@ func (t SectorFileType) SealSpaceUse(ssize abi.SectorSize) (uint64, error) {
 	return need, nil
 }
 
-// The method takes in two parameters: allowTypes and denyTypes, both of which are slices of strings.
+// SubAllowed takes in two parameters: allowTypes and denyTypes, both of which are slices of strings.
 // If allowTypes is not empty, the method sets a denyMask with all bits set to 1, and then iterates over each allowType,
 // converting it to a SectorFileType using the TypeFromString function and unsetting the corresponding bit in the denyMask.
 // If a string in allowTypes cannot be converted to a valid SectorFileType, it is ignored.

storage/sealer/storiface/resources.go

@@ -47,8 +47,9 @@ Percent of threads to allocate to parallel tasks
 var ParallelNum uint64 = 92
 var ParallelDenom uint64 = 100
 
-// TODO: Take NUMA into account
 func (r Resources) Threads(wcpus uint64, gpus int) uint64 {
+	// TODO: Take NUMA into account
+
 	mp := r.MaxParallelism
 
 	if r.GPUUtilization > 0 && gpus > 0 && r.MaxParallelismGPU != 0 { // task can use GPUs and worker has some

storage/wdpost/wdpost_run.go

@@ -523,6 +523,9 @@ func (s *WindowPoStScheduler) runPoStCycle(ctx context.Context, manual bool, di
 	return posts, nil
 }
 
+// BatchPartitions splits partitions into batches of partitions, so as not to exceed the number of
+// sectors allowed in a single message.
+//
 // Note: Partition order within batches must match original partition order in order
 // for code following the user code to work
 func (s *WindowPoStScheduler) BatchPartitions(partitions []api.Partition, nv network.Version) ([][]api.Partition, error) {