Skip to content

Commit

Permalink
multi: Go 1.19 doc comment formatting.
Browse files Browse the repository at this point in the history 
This modifies the entire repository to use the new formatting of doc
comments in the upcoming Go 1.19 release.

The primary motivating factors for this are:

- Builds check that files are formatted per gofmt and that will no
  longer be true as of Go 1.19 without these changes
- Separating all the updates into a single commit ensures these
  documentation only formatting changes do not clutter up diffs that
  actually change code

For the most part, the changes are just the automated changes suggested
by the Go 1.19 version of gofmt, but there are also a few cases where
the comments were reworded a bit to play nicely with the new formatting
requirements.

For example, the new version of gofmt reformats and collapses nested
lists where as the existing version does not.  Thus, instances of nested
lists have been changed to either eliminate them or use mixed markers
which produce expect results.
  • Loading branch information
@davecgh
davecgh committed Jul 30, 2022
1 parent 5c49ffb commit ad02d8f
Show file tree
Hide file tree
Showing 76 changed files with 1,217 additions and 1,120 deletions.
4 changes: 2 additions & 2 deletions addrmgr/doc.go
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
// Copyright (c) 2014 The btcsuite developers
// Copyright (c) 2015-2016 The Decred developers
// Copyright (c) 2015-2022 The Decred developers
// Use of this source code is governed by an ISC
// license that can be found in the LICENSE file.

/*
Package addrmgr implements concurrency safe Decred address manager.
Address Manager Overview
# Address Manager Overview
In order maintain the peer-to-peer Decred network, there needs to be a source
of addresses to connect to as nodes come and go. The Decred protocol provides
Expand Down
104 changes: 58 additions & 46 deletions blockchain/chaingen/generator.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -423,10 +423,10 @@ func newTxOut(amount int64, pkScriptVer uint16, pkScript []byte) *wire.TxOut {

// addCoinbaseTxOutputs adds the following outputs to the provided transaction
// which is assumed to be a coinbase transaction:
// - First output pays the development subsidy portion to the dev org
// - Second output is a standard provably prunable data-only coinbase output
// - Third and subsequent outputs pay the pow subsidy portion to the generic
// OP_TRUE p2sh script hash
// - First output pays the development subsidy portion to the dev org
// - Second output is a standard provably prunable data-only coinbase output
// - Third and subsequent outputs pay the pow subsidy portion to the generic
// OP_TRUE p2sh script hash
func (g *Generator) addCoinbaseTxOutputs(tx *wire.MsgTx, blockHeight uint32, devSubsidy, powSubsidy dcrutil.Amount) {
// First output is the developer subsidy.
tx.AddTxOut(&wire.TxOut{
Expand Down Expand Up @@ -750,10 +750,10 @@ func voteBitsScript(bits uint16, voteVersion uint32) []byte {
// original commitments.
//
// The transaction consists of the following outputs:
// - First output is an OP_RETURN followed by the block hash and height
// - Second output is an OP_RETURN followed by the vote bits
// - Third and subsequent outputs are the payouts according to the ticket
// commitments and the appropriate proportion of the vote subsidy.
// - First output is an OP_RETURN followed by the block hash and height
// - Second output is an OP_RETURN followed by the vote bits
// - Third and subsequent outputs are the payouts according to the ticket
// commitments and the appropriate proportion of the vote subsidy.
func (g *Generator) CreateVoteTx(voteBlock *wire.MsgBlock, ticketTx *wire.MsgTx, ticketBlockHeight, ticketBlockIndex uint32) *wire.MsgTx {
// Calculate the proof-of-stake subsidy proportion based on the block
// height.
Expand Down Expand Up @@ -890,16 +890,16 @@ func (g *Generator) limitRetarget(oldDiff, newDiff int64) int64 {
// the block after the current tip block the generator is associated with.
//
// An overview of the algorithm is as follows:
// 1) Use the proof-of-work limit for all blocks before the first retarget
// window
// 2) Use the previous block's difficulty if the next block is not at a retarget
// interval
// 3) Calculate the ideal retarget difficulty for each window based on the
// actual timespan of the window versus the target timespan and exponentially
// weight each difficulty such that the most recent window has the highest
// weight
// 4) Calculate the final retarget difficulty based on the exponential weighted
// average and ensure it is limited to the max retarget adjustment factor
// 1. Use the proof-of-work limit for all blocks before the first retarget
// window
// 2. Use the previous block's difficulty if the next block is not at a
// retarget interval
// 3. Calculate the ideal retarget difficulty for each window based on the
// actual timespan of the window versus the target timespan and
// exponentially weight each difficulty such that the most recent window has
// the highest weight
// 4. Calculate the final retarget difficulty based on the exponential weighted
// average and ensure it is limited to the max retarget adjustment factor
func (g *Generator) CalcNextRequiredDifficulty() uint32 {
// Target difficulty before the first retarget interval is the pow
// limit.
Expand Down Expand Up @@ -1303,7 +1303,8 @@ func winningTickets(voteBlock *wire.MsgBlock, liveTickets []*stakeTicket, numVot
// calcFinalLotteryState calculates the final lottery state for a set of winning
// tickets and the associated deterministic prng state hash after selecting the
// winners. It is the first 6 bytes of:
// blake256(firstTicketHash || ... || lastTicketHash || prngStateHash)
//
// blake256(firstTicketHash || ... || lastTicketHash || prngStateHash)
func calcFinalLotteryState(winners []*stakeTicket, prngStateHash chainhash.Hash) [6]byte {
data := make([]byte, (len(winners)+1)*chainhash.HashSize)
for i := 0; i < len(winners); i++ {
Expand Down Expand Up @@ -1363,7 +1364,7 @@ func hashMerkleBranches(left *chainhash.Hash, right *chainhash.Hash) *chainhash.
//
// The above stored as a linear array is as follows:
//
// [h1 h2 h3 h4 h12 h34 root]
// [h1 h2 h3 h4 h12 h34 root]
//
// As the above shows, the merkle root is always the last element in the array.
//
Expand Down Expand Up @@ -1454,18 +1455,21 @@ func hashToBig(hash *chainhash.Hash) *big.Int {
// Like IEEE754 floating point, there are three basic components: the sign,
// the exponent, and the mantissa. They are broken out as follows:
//
// * the most significant 8 bits represent the unsigned base 256 exponent
// * bit 23 (the 24th bit) represents the sign bit
// * the least significant 23 bits represent the mantissa
// 1. the most significant 8 bits represent the unsigned base 256 exponent
// 2. zero-based bit 23 (the 24th bit) represents the sign bit
// 3. the least significant 23 bits represent the mantissa
//
// Diagram:
//
// -------------------------------------------------
// | Exponent | Sign | Mantissa |
// -------------------------------------------------
// |-----------------------------------------------|
// | 8 bits [31-24] | 1 bit [23] | 23 bits [22-00] |
// -------------------------------------------------
//
// The formula to calculate N is:
// N = (-1^sign) * mantissa * 256^(exponent-3)
//
// N = (-1^sign) * mantissa * 256^(exponent-3)
//
// This compact form is only used in Decred to encode unsigned 256-bit numbers
// which represent difficulty targets, thus there really is not a need for a
Expand Down Expand Up @@ -2197,44 +2201,52 @@ func updateVoteCommitments(block *wire.MsgBlock) {
// generator and updates the generator's tip to the newly generated block.
//
// The block will include the following:
// - A coinbase with the following outputs:
//
// 1. A coinbase with the following outputs:
//
// - One that pays the required 10% subsidy to the dev org
// - One that contains a standard coinbase OP_RETURN script
// - Six that pay the required 60% subsidy to an OP_TRUE p2sh script
// - When a spendable output is provided:
//
// 2. When a spendable output is provided:
//
// - A transaction that spends from the provided output the following outputs:
// - One that pays the inputs amount minus 1 atom to an OP_TRUE p2sh script
// - Once the coinbase maturity has been reached:
// - One that pays the inputs amount minus 1 atom to an OP_TRUE p2sh script
//
// 3. Once the coinbase maturity has been reached:
//
// - A ticket purchase transaction (sstx) for each provided ticket spendable
// output with the following outputs:
// - One OP_SSTX output that grants voting rights to an OP_TRUE p2sh script
// - One OP_RETURN output that contains the required commitment and pays
// the subsidy to an OP_TRUE p2sh script
// - One OP_SSTXCHANGE output that sends change to an OP_TRUE p2sh script
// - Once the stake validation height has been reached:
// - One OP_SSTX output that grants voting rights to an OP_TRUE p2sh script
// - One OP_RETURN output that contains the required commitment and pays
// the subsidy to an OP_TRUE p2sh script
// - One OP_SSTXCHANGE output that sends change to an OP_TRUE p2sh script
//
// 4. Once the stake validation height has been reached:
//
// - 5 vote transactions (ssgen) as required according to the live ticket
// pool and vote selection rules with the following outputs:
// - One OP_RETURN followed by the block hash and height being voted on
// - One OP_RETURN followed by the vote bits
// - One or more OP_SSGEN outputs with the payouts according to the original
// ticket commitments
// - One OP_RETURN followed by the block hash and height being voted on
// - One OP_RETURN followed by the vote bits
// - One or more OP_SSGEN outputs with the payouts according to the original
// ticket commitments
// - Revocation transactions (ssrtx) as required according to any missed votes
// with the following outputs:
// - One or more OP_SSRTX outputs with the payouts according to the original
// ticket commitments
// - One or more OP_SSRTX outputs with the payouts according to the original
// ticket commitments
//
// Additionally, if one or more munge functions are specified, they will be
// invoked with the block prior to solving it. This provides callers with the
// opportunity to modify the block which is especially useful for testing.
//
// In order to simply the logic in the munge functions, the following rules are
// applied after all munge functions have been invoked:
// - All votes will have their commitments updated if the previous hash or
// height was manually changed after stake validation height has been reached
// - The merkle root will be recalculated unless it was manually changed
// - The stake root will be recalculated unless it was manually changed
// - The size of the block will be recalculated unless it was manually changed
// - The block will be solved unless the nonce was changed
// - All votes will have their commitments updated if the previous hash or
// height was manually changed after stake validation height has been reached
// - The merkle root will be recalculated unless it was manually changed
// - The stake root will be recalculated unless it was manually changed
// - The size of the block will be recalculated unless it was manually changed
// - The block will be solved unless the nonce was changed
func (g *Generator) NextBlock(blockName string, spend *SpendableOut, ticketSpends []SpendableOut, mungers ...func(*wire.MsgBlock)) *wire.MsgBlock {
// Prevent block name collisions.
if g.blocksByName[blockName] != nil {
Expand Down
16 changes: 8 additions & 8 deletions blockchain/stake/internal/ticketdb/chainio.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -354,17 +354,17 @@ func DbPutBestState(dbTx database.Tx, bcs BestChainState) error {
// The last 3 are encoded as a single byte of flags.
// The flags describe a particular state for the ticket:
// 1. Missed is set, but revoked and spent are not (0000 0001). The ticket
// was selected in the lottery at this block height but missed, or the
// ticket became too old and was missed. The ticket is being moved to the
// missed ticket bucket from the live ticket bucket.
// was selected in the lottery at this block height but missed, or the
// ticket became too old and was missed. The ticket is being moved to the
// missed ticket bucket from the live ticket bucket.
// 2. Missed and revoked are set (0000 0011). The ticket was missed
// previously at a block before this one and was revoked, and
// as such is being moved to the revoked ticket bucket from the
// missed ticket bucket.
// previously at a block before this one and was revoked, and
// as such is being moved to the revoked ticket bucket from the
// missed ticket bucket.
// 3. Spent is set (0000 0100). The ticket has been spent and is removed
// from the live ticket bucket.
// from the live ticket bucket.
// 4. No flags are set. The ticket was newly added to the live ticket
// bucket this block as a maturing ticket.
// bucket this block as a maturing ticket.
type UndoTicketData struct {
TicketHash chainhash.Hash
TicketHeight uint32
Expand Down
66 changes: 36 additions & 30 deletions blockchain/stake/staketx.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -706,7 +706,9 @@ func CalculateRevocationRewards(contribAmounts []int64, ticketPurchaseAmount int
// OP_SSTXCHANGE tagged output for input 2 [index 4]
// ...
// OP_RETURN push of input MaxInputsPerSStx's address for reward receiving
// [index (MaxInputsPerSStx*2)-2]
//
// [index (MaxInputsPerSStx*2)-2]
//
// OP_SSTXCHANGE tagged output [index (MaxInputsPerSStx*2)-1]
//
// The output OP_RETURN pushes should be of size 20 bytes (standard address).
Expand Down Expand Up @@ -962,28 +964,30 @@ func GetSSGenTreasuryVotes(PkScript []byte) ([]TreasuryVoteTuple, error) {
// SSGen transactions are specified as below.
//
// Inputs:
// [index 0] Stakebase null input
// [index 1] SStx-tagged output
//
// [index 0] Stakebase null input
// [index 1] SStx-tagged output
//
// Outputs:
// [index 0] OP_RETURN push of 40 bytes containing:
// i. 32-byte block header of block being voted on.
// ii. 8-byte int of this block's height.
// [index 1] OP_RETURN push of 2 bytes containing votebits
// [index 2] SSGen-tagged output to the first payment commitment address from
// SStx-tagged output's tx (output index 1)
// [index 3] SSGen-tagged output to the second payment commitment address from
// SStx-tagged output's tx (output index 3)
// ...
// [index maxOuts - 2] SSGen-tagged output to the last payment
// commitment address from SStx-tagged output's tx index output (output
// index MaxInputsPerSStx - 1)
// [index maxOuts - 1] OP_RETURN push of 2 bytes containing opcode
// designating what the remaining data that is pushed is. In the case of
// 'TV' (Treasury Vote) it checks for a <hash><vote> tuple. For example:
// OP_RETURN OP_DATA_X 'T','V' <N hashvote_tuple>
// NOTE: This output is only appended when a treasury spend is being voted
// on.
//
// [index 0] OP_RETURN push of 40 bytes containing:
// i. 32-byte block header of block being voted on.
// ii. 8-byte int of this block's height.
// [index 1] OP_RETURN push of 2 bytes containing votebits
// [index 2] SSGen-tagged output to the first payment commitment address from
// SStx-tagged output's tx (output index 1)
// [index 3] SSGen-tagged output to the second payment commitment address from
// SStx-tagged output's tx (output index 3)
// ...
// [index maxOuts - 2] SSGen-tagged output to the last payment
// commitment address from SStx-tagged output's tx index output (output
// index MaxInputsPerSStx - 1)
// [index maxOuts - 1] OP_RETURN push of 2 bytes containing opcode
// designating what the remaining data that is pushed is. In the case of
// 'TV' (Treasury Vote) it checks for a <hash><vote> tuple. For example:
// OP_RETURN OP_DATA_X 'T','V' <N hashvote_tuple>
// NOTE: This output is only appended when a treasury spend is being voted
// on.
func CheckSSGenVotes(tx *wire.MsgTx) ([]TreasuryVoteTuple, error) {
// Check to make sure there aren't too many inputs.
if len(tx.TxIn) != NumInputsPerSSGen {
Expand Down Expand Up @@ -1172,17 +1176,19 @@ func IsSSGen(tx *wire.MsgTx) bool {
// SSRtx transactions are specified as below.
//
// Inputs:
// [index 0] SStx-tagged output
//
// [index 0] SStx-tagged output
//
// Outputs:
// [index 0] SSRtx-tagged output to the first payment commitment address from
// SStx-tagged output's tx (output index 1)
// [index 1] SSRtx-tagged output to the second payment commitment address from
// SStx-tagged output's tx (output index 3)
// ...
// [index MaxOutputsPerSSRtx - 1] SSRtx-tagged output to the last payment
// commitment address from SStx-tagged output's tx index output (output
// index MaxInputsPerSStx - 1)
//
// [index 0] SSRtx-tagged output to the first payment commitment address from
// SStx-tagged output's tx (output index 1)
// [index 1] SSRtx-tagged output to the second payment commitment address from
// SStx-tagged output's tx (output index 3)
// ...
// [index MaxOutputsPerSSRtx - 1] SSRtx-tagged output to the last payment
// commitment address from SStx-tagged output's tx index output (output
// index MaxInputsPerSStx - 1)
func CheckSSRtx(tx *wire.MsgTx) error {
// Check to make sure there is the correct number of inputs.
if len(tx.TxIn) != NumInputsPerSSRtx {
Expand Down
10 changes: 6 additions & 4 deletions blockchain/stake/tickets.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -461,9 +461,10 @@ func hashInSlice(h chainhash.Hash, list []chainhash.Hash) bool {
// safeGet fetches a pointer to the data for the key in the treap, then
// copies the value so that the original pointer to the key is never written
// to accidentally later.
// TODO This function could also check to make sure the states of the ticket
// treap value are valid.
func safeGet(t *tickettreap.Immutable, k tickettreap.Key) (*tickettreap.Value, error) {
// TODO: This function could also check to make sure the states of the
// ticket treap value are valid.

v := t.Get(k)
if v == nil {
str := fmt.Sprintf("ticket %v was supposed to be in the passed "+
Expand All @@ -483,9 +484,10 @@ func safeGet(t *tickettreap.Immutable, k tickettreap.Key) (*tickettreap.Value, e
// safePut is used to put a value into an immutable ticket treap, returning
// the mutated, immutable treap given as a result. It first checks to see if
// there is already this key in the treap. If there is, it returns an error.
// TODO This function could also check to make sure the states of the ticket
// treap value are valid.
func safePut(t *tickettreap.Immutable, k tickettreap.Key, v *tickettreap.Value) (*tickettreap.Immutable, error) {
// TODO This function could also check to make sure the states of the ticket
// treap value are valid.

if t.Has(k) {
str := fmt.Sprintf("attempted to insert duplicate key %v into treap",
chainhash.Hash(k))
Expand Down
Loading

0 comments on commit ad02d8f

Please sign in to comment.