From 0d374ffc6b086eb6a1e7ac3b1bcce9146f656389 Mon Sep 17 00:00:00 2001
From: gziolo <gziolo@git.wordpress.org>
Date: Thu, 8 Feb 2024 08:37:09 +0000
Subject: [PATCH] Editor: Improve code documentation for block bindings

Follow-up [57514].
See #60282.
Props czapla, gziolo, retrofox.


Built from https://develop.svn.wordpress.org/trunk@57560


git-svn-id: http://core.svn.wordpress.org/trunk@57061 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/block-bindings.php                | 58 +++++++++++++++++--
 .../class-wp-block-bindings-registry.php      |  5 ++
 wp-includes/version.php                       |  2 +-
 3 files changed, 60 insertions(+), 5 deletions(-)

diff --git a/wp-includes/block-bindings.php b/wp-includes/block-bindings.php
index 4fc58c3325..7094313959 100644
--- a/wp-includes/block-bindings.php
+++ b/wp-includes/block-bindings.php
@@ -12,10 +12,60 @@
 /**
  * Registers a new block bindings source.
  *
- * Sources are used to override block's original attributes with a value
- * coming from the source. Once a source is registered, it can be used by a
- * block by setting its `metadata.bindings` attribute to a value that refers
- * to the source.
+ * Registering a source consists of defining a **name** for that source and a callback function specifying
+ * how to get a value from that source and pass it to a block attribute.
+ *
+ * Once a source is registered, any block that supports the Block Bindings API can use a value
+ * from that source by setting its `metadata.bindings` attribute to a value that refers to the source.
+ *
+ * Note that `register_block_bindings_source()` should be called from a handler attached to the `init` hook.
+ *
+ *
+ * ## Example
+ *
+ * ### Registering a source
+ *
+ * First, you need to define a function that will be used to get the value from the source.
+ *
+ *     function my_plugin_get_custom_source_value( array $source_args, $block_instance, string $attribute_name ) {
+ *       // Your custom logic to get the value from the source.
+ *       // For example, you can use the `$source_args` to look up a value in a custom table or get it from an external API.
+ *       $value = $source_args['key'];
+ *
+ *       return "The value passed to the block is: $value"
+ *     }
+ *
+ * The `$source_args` will contain the arguments passed to the source in the block's
+ * `metadata.bindings` attribute. See the example in the "Usage in a block" section below.
+ *
+ *     function my_plugin_register_block_bindings_sources() {
+ *       register_block_bindings_source( 'my-plugin/my-custom-source', array(
+ *         'label'              => __( 'My Custom Source', 'my-plugin' ),
+ *         'get_value_callback' => 'my_plugin_get_custom_source_value',
+ *       ) );
+ *     }
+ *     add_action( 'init', 'my_plugin_register_block_bindings_sources' );
+ *
+ * ### Usage in a block
+ *
+ * In a block's `metadata.bindings` attribute, you can specify the source and
+ * its arguments. Such a block will use the source to override the block
+ * attribute's value. For example:
+ *
+ *     <!-- wp:paragraph {
+ *       "metadata": {
+ *         "bindings": {
+ *           "content": {
+ *             "source": "my-plugin/my-custom-source",
+ *             "args": {
+ *               "key": "you can pass any custom arguments here"
+ *             }
+ *           }
+ *         }
+ *       }
+ *     } -->
+ *     <p>Fallback text that gets replaced.</p>
+ *     <!-- /wp:paragraph -->
  *
  * @since 6.5.0
  *
diff --git a/wp-includes/class-wp-block-bindings-registry.php b/wp-includes/class-wp-block-bindings-registry.php
index 28e8b1b601..edde1a0cb8 100644
--- a/wp-includes/class-wp-block-bindings-registry.php
+++ b/wp-includes/class-wp-block-bindings-registry.php
@@ -35,6 +35,11 @@ final class WP_Block_Bindings_Registry {
 	/**
 	 * Registers a new block bindings source.
 	 *
+	 * This is a low-level method. For most use cases, it is recommended to use
+	 * the `register_block_bindings_source()` function instead.
+	 *
+	 * @see register_block_bindings_source()
+	 *
 	 * Sources are used to override block's original attributes with a value
 	 * coming from the source. Once a source is registered, it can be used by a
 	 * block by setting its `metadata.bindings` attribute to a value that refers
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 1765d5a246..e9d9085807 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.5-alpha-57559';
+$wp_version = '6.5-alpha-57560';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.