Repository: bitcoin/bitcoin
File: src/kernel/bitcoinkernel.h (C/C++)

Code before:
    btck_ContextOptions* context_options,
    btck_ValidationInterfaceCallbacks validation_interface_callbacks) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * Destroy the context options.
 */
BITCOINKERNEL_API void btck_context_options_destroy(btck_ContextOptions* context_options);

///@}

/** @name Context
 * Functions for working with contexts.
 */
///@{

/**
 * @brief Create a new kernel context. If the options have not been previously
 * set, their corresponding fields will be initialized to default values; the
 * context will assume mainnet chain parameters and won't attempt to call the
 * kernel notification callbacks.
 *
 * @param[in] context_options Nullable, created by @ref btck_context_options_create.
 * @return                    The allocated context, or null on error.
 */
BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_create(
    const btck_ContextOptions* context_options);

/**
 * Copy the context.
 */
BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_copy(
    const btck_Context* context) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Interrupt can be used to halt long-running validation functions like
 * when reindexing, importing or processing blocks.
 *
 * @param[in] context  Non-null.
 * @return             0 if the interrupt was successful, non-zero otherwise.
 */
BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_interrupt(
    btck_Context* context) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * Destroy the context.
 */
BITCOINKERNEL_API void btck_context_destroy(btck_Context* context);

///@}

/** @name BlockTreeEntry

Review comment (suggestion):
Not sure but "Must be destroyed ..." docs may not be necessary as we have not documented this for the rest of the owned returned pointers (e.g. `btck_Block*`).

<details>
<summary>diff</summary>

```diff
diff --git a/src/kernel/bitcoinkernel.h b/src/kernel/bitcoinkernel.h
index 89b69b849d..a980000968 100644
--- a/src/kernel/bitcoinkernel.h
+++ b/src/kernel/bitcoinkernel.h
@@ -918,7 +918,7 @@ BITCOINKERNEL_API const btck_BlockTreeEntry* BITCOINKERNEL_WARN_UNUSED_RESULT bt
  * @brief Return the block header associated with this entry.
  *
  * @param[in] block_tree_entry Non-null.
- * @return                     Block Header, or null on error. Must be destroyed with btck_block_header_destroy().
+ * @return                     Block Header, or null on error.
  */
 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_tree_entry_get_block_header(
     const btck_BlockTreeEntry* block_tree_entry) BITCOINKERNEL_ARG_NONNULL(1);
@@ -1196,7 +1196,7 @@ BITCOINKERNEL_API const btck_Transaction* BITCOINKERNEL_WARN_UNUSED_RESULT btck_
  * Creates a new block header object from the block's header data.
  *
  * @param[in] block Non-null block
- * @return          Block Header, or null on error. Must be destroyed with btck_block_header_destroy().
+ * @return          Block Header, or null on error.
  */
 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_get_header(
     const btck_Block* block) BITCOINKERNEL_ARG_NONNULL(1);
@@ -1652,7 +1652,7 @@ BITCOINKERNEL_API void btck_block_hash_destroy(btck_BlockHash* block_hash);
  *
  * @param[in] raw_block_header      Non-null, serialized header data (80 bytes)
  * @param[in] raw_block_header_len  Length of serialized header (must be 80)
- * @return                          Block Header, or null on error. Must be destroyed with btck_block_header_destroy().
+ * @return                          Block Header, or null on error.
  */
 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_create(
     const void* raw_block_header, size_t raw_block_header_len) BITCOINKERNEL_ARG_NONNULL(1);
@@ -1661,7 +1661,7 @@ BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_
  * @brief Copy a block header
  *
  * @param[in] header    Non-null header
- * @return              Copied header. Must be destroyed with btck_block_header_destroy().
+ * @return              Copied header.
  */
 BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_copy(
     const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1);
@@ -1670,7 +1670,7 @@ BITCOINKERNEL_API btck_BlockHeader* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_
  * @brief Get the block hash.
  *
  * @param[in] header    Non-null header
- * @return              Block hash. Must be destroyed btck_block_hash_destroy().
+ * @return              Block hash.
  */
 BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_header_get_hash(
     const btck_BlockHeader* header) BITCOINKERNEL_ARG_NONNULL(1);
```
</details>

Code after:
 * @brief Set the validation interface callbacks for the context options. The
 * context created with the options will be configured for these validation
 * interface callbacks. The callbacks will then be triggered from validation
 * events issued by the chainstate manager created from the same context.
 *
 * @param[in] context_options                Non-null, previously created with btck_context_options_create.
 * @param[in] validation_interface_callbacks The callbacks used for passing validation information to the
 *                                           user.
 */
BITCOINKERNEL_API void btck_context_options_set_validation_interface(
    btck_ContextOptions* context_options,
    btck_ValidationInterfaceCallbacks validation_interface_callbacks) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * Destroy the context options.
 */
BITCOINKERNEL_API void btck_context_options_destroy(btck_ContextOptions* context_options);

///@}

/** @name Context
 * Functions for working with contexts.
 */
///@{

/**
 * @brief Create a new kernel context. If the options have not been previously
 * set, their corresponding fields will be initialized to default values; the
 * context will assume mainnet chain parameters and won't attempt to call the
 * kernel notification callbacks.
 *
 * @param[in] context_options Nullable, created by @ref btck_context_options_create.
 * @return                    The allocated context, or null on error.
 */
BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_create(
    const btck_ContextOptions* context_options);

/**
 * Copy the context.
 */
BITCOINKERNEL_API btck_Context* BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_copy(
    const btck_Context* context) BITCOINKERNEL_ARG_NONNULL(1);

/**
 * @brief Interrupt can be used to halt long-running validation functions like
 * when reindexing, importing or processing blocks.
 *
 * @param[in] context  Non-null.
 * @return             0 if the interrupt was successful, non-zero otherwise.
 */
BITCOINKERNEL_API int BITCOINKERNEL_WARN_UNUSED_RESULT btck_context_interrupt(