kernel: document `btck_block_check` resets `validation_state` #35189

pull w0xlt wants to merge 1 commits into bitcoin:master from w0xlt:kernel_block_check_doc changing 1 files +5 −3

w0xlt commented at 1:01 AM on May 1, 2026: contributor

btck_block_check resets the caller-supplied btck_BlockValidationState on entry (state = BlockValidationState{}; in bitcoinkernel.cpp), but the public header doesn't say so. validation_state is tagged [in,out] and the description only mentions that the result is written, not that prior contents are discarded. No behavior change, no API change.

kernel: document btck_block_check resets validation_state

The implementation does state = BlockValidationState{} on entry, but
the doc tagged validation_state as [in,out] and said nothing about the
discard. Re-tag as [out] and state explicitly that any prior contents
are overwritten, matching the wording used for btck_transaction_check.

ed81aca01a

DrahtBot added the label Validation on May 1, 2026
DrahtBot commented at 1:01 AM on May 1, 2026: contributor



The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.



Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35189.



Reviews

See the guideline for information on the review process.

Type Reviewers

ACK sedited

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.
sedited approved
sedited commented at 7:53 AM on May 1, 2026: contributor

ACK ed81aca01a058daa3d9b2d15f0db52bf38487879
sedited commented at 7:59 AM on May 1, 2026: contributor

I wonder what the better pattern is here. Should we always be resetting them?
?
added_to_project_v2 fanquake
?
project_v2_item_status_changed github-project-automation[bot]

Type	Reviewers
ACK	sedited

in src/kernel/bitcoinkernel.h:1309 in ed81aca01a

1307 | - *                                  btck_block_validation_state_create and updated
1308 | - *                                  in-place with the validation result.
1309 | + * @param[out]    validation_state  Non-null, previously created with
1310 | + *                                  btck_block_validation_state_create. Reset on
1311 | + *                                  entry (any prior contents are overwritten) and
1312 | + *                                  updated in-place with the validation result

maflcko commented at 3:04 PM on May 5, 2026:

Doesn't "updated in-place" imply that any value is overwritten? I think it would be better to only document the out-params that are not always updated in-place and overwritten. (or rather, try to always update them and overwrite them, where possible)

Contributors

Labels

kernel: document `btck_block_check` resets `validation_state` #35189

Code Coverage & Benchmarks

Reviews