kernel: doc: explain return value for `btck

theStack commented at 5:11 pm on March 11, 2026: contributor

Note that this is the only callback type with a non-void return type. Probably it would make sense to document the parameters of callbacks as well on the long-term (Doxygen style?), but this IMHO the most critical missing documentation, where likely other bitcoinkernel users working with the C API could trip over too.

Background: I’ve been working on btck bindings for Zig for a while [1]. Overall I found the C API header bitcoinkernel.h very well-documented and to a large degree self-explanatory, but for implementing a btck_WriteBytes callback (needed for various btck_..._to_bytes serialization functions) I had to look into the kernel implementation to figure out what return value is expected.

[1] still not public and put on hold for the last few months due to lib(std)c++ build system / linking issues (needing ugly workarounds, hopefully improved with Zig’s upcoming 0.16 release); now continued, hopefully ready to be published in a first presentable version soon(tm)

kernel: doc: explain return value for `btck_WriteBytes` callback

This is the only non-void callback type, so it makes sense to document what
implementers should return.

ec4ec91d59

DrahtBot added the label Validation on Mar 11, 2026

DrahtBot commented at 5:11 pm on March 11, 2026: contributor

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

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	sedited, alexanderwiederin, stickies-v

If your review is incorrectly listed, please copy-paste <!–meta-tag:bot-skip–> into the comment that the bot should ignore.

sedited approved

sedited commented at 7:38 pm on March 11, 2026: contributor

ACK ec4ec91d59b25badf212bf0aee0ad5c1eead7ff1

Thanks for contributing, looking forward to your bindings!

sedited requested review from alexanderwiederin on Mar 11, 2026

sedited requested review from stickies-v on Mar 11, 2026

alexanderwiederin approved

alexanderwiederin commented at 7:59 pm on March 11, 2026: none

Why not align with the *_to_bytes methods?

0* [@return](/bitcoin-bitcoin/contributor/return/) 0 on success.

ACK https://github.com/bitcoin/bitcoin/pull/34807/changes/ec4ec91d59b25badf212bf0aee0ad5c1eead7ff1

theStack commented at 11:25 pm on March 11, 2026: contributor

Why not align with the *_to_bytes methods?
0* [@return](/bitcoin-bitcoin/contributor/return/) 0 on success.

Considered that, but decided against for consistency reasons, as the other part in the comment block (“Function signature for…”) is not in Doxygen style either. Happy to change though if reviewers feel strongly.

in src/kernel/bitcoinkernel.h:353 in ec4ec91d59

348@@ -349,6 +349,8 @@ typedef void (*btck_ValidationInterfaceBlockDisconnected)(void* user_data, btck_
349 
350 /**
351  * Function signature for serializing data.
352+ *
353+ * Returns 0 to indicate success.

stickies-v commented at 3:16 am on March 12, 2026:

Not necessary, but I also think increased doxygen adherence would be better since it’s generally used in this header’s documentation anyway.

Also, I think highlighting that the function can be called multiple times (through the serialization framework) would be helpful. And we don’t do this elsewhere, but the current documentation doesn’t say that failure must be non-zero, so could make that explicit (even if most people would assume that already).

My best effort docstring:

 0diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
 1index 57c88c1279..761959e9d1 100644
 2--- a/src/kernel/bitcoinkernel.h
 3+++ b/src/kernel/bitcoinkernel.h
 4@@ -347,10 +347,17 @@ typedef void (*btck_ValidationInterfacePoWValidBlock)(void* user_data, btck_Bloc
 5 typedef void (*btck_ValidationInterfaceBlockConnected)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry);
 6 typedef void (*btck_ValidationInterfaceBlockDisconnected)(void* user_data, btck_Block* block, const btck_BlockTreeEntry* entry);
 7 
 8-/**
 9- * Function signature for serializing data.
10- *
11- * Returns 0 to indicate success.
12+/**                                                                                                                          
13+ * [@brief](/bitcoin-bitcoin/contributor/brief/) Callback for writing serialized byte data.                                                                         
14+ *                                                                                                                           
15+ * May be called multiple times for a single serialization. Implementations                                                  
16+ * should append rather than overwrite previously written data.
17+ *
18+ * [@param](/bitcoin-bitcoin/contributor/param/)[in] bytes    Non-null, pointer to the data to write.
19+ * [@param](/bitcoin-bitcoin/contributor/param/)[in] size     Number of bytes to write.
20+ * [@param](/bitcoin-bitcoin/contributor/param/)[in] userdata Nullable, holds a user-defined opaque structure, passed
21+ *                     through from the calling serialization function.
22+ * [@return](/bitcoin-bitcoin/contributor/return/)             0 on success, non-zero on failure.
23  */
24 typedef int (*btck_WriteBytes)(const void* bytes, size_t size, void* userdata);
25

theStack commented at 2:44 pm on March 12, 2026:

Agree that the “can be called multiple times” aspect is worthwhile to document as well, IIRC that also caught me by surprise back then. The docstring looks good to me, I’d be happy to ACK it on a follow-up PR (maybe one that adds missing docstrings also for other callbacks, if deemed necessary).

stickies-v approved

stickies-v commented at 3:16 am on March 12, 2026: contributor

ACK ec4ec91d59b25badf212bf0aee0ad5c1eead7ff1

fanquake merged this on Mar 12, 2026

fanquake closed this on Mar 12, 2026

theStack deleted the branch on Mar 12, 2026

kernel: doc: explain return value for btck_WriteBytes callback #34807

Reviews

kernel: doc: explain return value for `btck_WriteBytes` callback #34807