WordPress · VladimirAus · Jul 20, 2025 · Jul 20, 2025 · Jul 20, 2025 · Jul 20, 2025
diff --git a/src/wp-includes/rest-api.php b/src/wp-includes/rest-api.php
@@ -19,16 +19,60 @@
  *
  * Note: Do not use before the {@see 'rest_api_init'} hook.
  *
+ * Example usage:
+ * ```php
+ * add_action( 'rest_api_init', function () {
+ *   register_rest_route( 'my-plugin/v1', '/settings', array(
+ *     'methods'  => 'GET',
+ *     'callback' => 'my_plugin_get_settings',
+ *     'permission_callback' => function () {
+ *       // Only allow users who can manage options.
+ *       return current_user_can( 'manage_options' );
+ *     },
+ *   ) );
+ * } );
+ * ```
+ *
  * @since 4.4.0
  * @since 5.1.0 Added a `_doing_it_wrong()` notice when not called on or after the `rest_api_init` hook.
  * @since 5.5.0 Added a `_doing_it_wrong()` notice when the required `permission_callback` argument is not set.
  *
  * @param string $route_namespace The first URL segment after core prefix. Should be unique to your package/plugin.
- * @param string $route           The base URL for route you are adding.
- * @param array  $args            Optional. Either an array of options for the endpoint, or an array of arrays for
- *                                multiple methods. Default empty array.
- * @param bool   $override        Optional. If the route already exists, should we override it? True overrides,
- *                                false merges (with newer overriding if duplicate keys exist). Default false.
+ * @param string $route           The base URL for route to be added with support for regular expressions.
+ *                                Example: '/posts/(?P<id>[\d]+)'.
+ * @param array $args             {
+ *                                    Optional. An array of options for the endpoint. This can be a single associative
+ *                                    array for one endpoint, or an array of associative arrays for multiple endpoints.
+ *                                    Default empty array.
+ *
+ *                                    @type string|array $methods             Required. HTTP method(s) the route
+ *                                                                            responds to. Can be a string or an array
+ *                                                                            (e.g. 'GET', 'POST', ['GET', 'POST']).
+ *                                    @type callable     $callback            Required. The callback function to handle
+ *                                                                            the request. Accepts a `WP_REST_Request`
+ *                                                                            and returns a `WP_REST_Response` or array.
+ *                                    @type callable     $permission_callback Required. A function to check if the
+ *                                                                            request has permission. Must return
+ *                                                                            `true` or `WP_Error`.
+ *                                    @type array        $args {
+ *                                        Optional. An associative array of argument schema for validation and
+ *                                        sanitization.
+ *                                        Keys are argument names, values are arrays of argument options:
+ *
+ *                                        @type bool     $required           Whether this parameter is required.
+ *                                                                           Default false.
+ *                                        @type string   $type               Data type: 'string', 'integer', 'boolean',
+ *                                                                           'array', etc.
+ *                                        @type mixed    $default            Default value if the parameter is not
+ *                                                                           provided.
+ *                                        @type callable $validate_callback  Callback to validate the parameter.
+ *                                        @type callable $sanitize_callback  Callback to sanitize the parameter.
+ *                                        @type array    $enum               Allowed values (enumeration).
+ *                                        @type array    $items              Schema for array items if type is 'array'.
+ *                                                             }
+ *                                }
+ * @param bool   $override        Optional. True to override existing route, false to merge (with newer overriding
+ *                                if duplicate keys exist). Default false.
  * @return bool True on success, false on error.
  */
 function register_rest_route( $route_namespace, $route, $args = array(), $override = false ) {