[Documentation] Replaced `type` with [type] #6738

durkmurder · 2024-11-19T14:47:47Z

Context

Based on comment on recent PR this PR replaces usages of `type` with [type].

I have used following regex to find all type usages: `([a-zA-Z]+.[a-zA-Z]+)` and then next expression to replace: [$1]

…ub.com/onflow/flow-go into yurii/fix-incorrent-doc-formatting

…atting

codecov-commenter · 2024-11-19T14:51:04Z

Codecov Report

Attention: Patch coverage is 84.21053% with 6 lines in your changes missing coverage. Please review.

Project coverage is 41.72%. Comparing base (d0c9695) to head (f7fbe57).

Files with missing lines	Patch %	Lines
consensus/hotstuff/validator/validator.go	57.14%	3 Missing ⚠️
engine/consensus/dkg/reactor_engine.go	0.00%	1 Missing ⚠️
module/dkg/client.go	0.00%	1 Missing ⚠️
network/validator/pubsub/topic_validator.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@                   Coverage Diff                    @@
##           feature/efm-recovery    #6738      +/-   ##
========================================================
+ Coverage                 41.70%   41.72%   +0.01%     
========================================================
  Files                      2030     2030              
  Lines                    180462   180462              
========================================================
+ Hits                      75261    75295      +34     
+ Misses                    99003    98976      -27     
+ Partials                   6198     6191       -7

Flag	Coverage Δ
unittests	`41.72% <84.21%> (+0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚨 Try these New Features:

Flaky Tests Detection - Detect and resolve failed and flaky tests

jordanschalm

Thanks for updating the documentation to add links. Unfortunately, the regex approach is not very accurate (I added a few comments pointing out places where the result won't work as expected).

Honestly I'm not sure it is worth our time to go back to fix existing type references (filtering through the diff to find the places where the regex didn't work). Rather, I think we should just keep this in mind for future code changes.

jordanschalm · 2024-11-19T16:08:19Z

cmd/util/ledger/migrations/cadence_values_migration_test.go

@@ -2733,7 +2733,7 @@ func TestTypeRequirementRemovalMigration(t *testing.T) {

 	contractName := "TiblesProducer"

-	// Store a value with the actual `TiblesProducer.Minter` type
+	// Store a value with the actual [TiblesProducer.Minter] type


This is referencing a Cadence smart contract, so the [] won't resolve as a link.

jordanschalm · 2024-11-19T16:09:19Z

consensus/hotstuff/cruisectl/proposal_timing.go

@@ -82,7 +82,7 @@ var _ ProposalTiming = (*happyPathBlockTime)(nil)
 //     In other words, when primary determines at what future time to broadcast the child, the child
 //     has _not_ been published and the `timedBlock` references the parent on the happy path (or another
 //     earlier block on the unhappy path)
-//   - `unconstrainedBlockTime` is the delay, relative to `timedBlock.TimeObserved` when the controller would
+//   - `unconstrainedBlockTime` is the delay, relative to [timedBlock.TimeObserved] when the controller would


timedBlock is an unexported name, so this won't resolve as a link.

jordanschalm · 2024-11-19T16:19:30Z

consensus/hotstuff/model/timeout.go

 	// timeout for this view. When the timer for the view's original duration expires, a `TimeoutObject`
-	// with `TimeoutTick = 0` is broadcast. Subsequently, `timeout.Controller` re-broadcasts the
+	// with `TimeoutTick = 0` is broadcast. Subsequently, [timeout.Controller] re-broadcasts the


This won't resolve as a link because it is documenting a struct field.

turbolent

Good idea to link the Go types in docstrings! However, there seem to be changes outside of docstrings that should be reverted

cmd/util/ledger/migrations/staged_contracts_migration_test.go

…om/onflow/flow-go into yurii/fix-incorrent-doc-formatting

durkmurder · 2024-11-19T16:33:47Z

@jordanschalm @turbolent It took me 5 mins to build a regex and replace everything. Pretty much low effort if you ask me. Even if it's not 100% accurate it shouldn't harm replacing all `` with []. As long as tests are passing I am pretty confident that it shouldn't cause a regression.

turbolent · 2024-11-19T23:47:48Z

Oh yeah, I think replacing linking all occurrences in docstrings if fine, even if they might not work, as long as we don't change non-docstring code 👍

AlexHentschel · 2024-11-22T22:48:59Z

fvm/fvm_blockcontext_test.go

@@ -250,7 +250,7 @@ func TestBlockContext_DeployContract(t *testing.T) {
 		require.NoError(t, output.Err)
 	})

-	t.Run("account with deployed contract has `contracts.names` filled", func(t *testing.T) {
+	t.Run("account with deployed contract has [contracts.names] filled", func(t *testing.T) {


Lets revert this, because its part of an code-string

AlexHentschel · 2024-11-22T22:49:42Z

module/epochs/epoch_lookup_test.go

@@ -211,7 +211,7 @@ func (suite *EpochLookupSuite) TestProtocolEvents_EpochExtended_SanityChecks() {
 		return ctx
 	}

-	suite.T().Run("sanity check: `extension.FinalView` should be greater than final view of latest epoch", func(t *testing.T) {
+	suite.T().Run("sanity check: [extension.FinalView] should be greater than final view of latest epoch", func(t *testing.T) {
