Commit 033183b4219 for woocommerce

commit 033183b42195aab88ba53ee69b3ccd42a5a88dc5
Author: Vlad Olaru <vlad.olaru@automattic.com>
Date:   Sun Aug 2 13:10:13 2026 +0300

    [docs] Correct the NoticeHandler::convert_notices_to_wp_errors docblock (#67307)

    * docs: correct the NoticeHandler::convert_notices_to_wp_errors docblock

    The docblock claimed "This method will discard notices once complete."
    It does not. The method counts error notices, returns early if there are
    none, builds a `WP_Error`, and returns — `wc_clear_notices()` is never
    called on any path.

    The claim is easy to believe because the sibling
    `convert_notices_to_exceptions()` carries the same sentence and does
    honour it, clearing before it throws and clearing again in the
    no-error case.

    Corrected the comment rather than the code, because the code is right for
    how the method is actually used. Its only caller,
    `CartController::validate_cart_items()`, snapshots the notice queue
    before firing `woocommerce_check_cart_items`, calls this method, then
    restores the snapshot — and the restore runs before the exception is
    thrown, so it always executes. Adding a clear inside the method would be
    redundant there, since the caller's restore overwrites the queue either
    way.

    It would not be redundant for everyone else. This is a public static
    method on a Store API utility class, so extensions can call it, and
    making it clear the queue would change behaviour for any caller relying
    on notices surviving. That is real backward-compatibility exposure in
    exchange for no in-tree benefit.

    The replacement text says what the method does and points at the calling
    convention, so the next reader does not "fix" the code to match the old
    comment.

    * docs: reference the correct caller in the NoticeHandler docblock

    The replacement text pointed at `CartController::validate_cart_items()`.
    The snapshot and restore of the notice queue are in
    `CartController::validate_cart()` — `$previous_notices` is captured at
    line 511, the call happens at 527, and the queue is restored at 530, all
    inside that method.

    `validate_cart_items()` does exist, and `validate_cart()` calls it, which
    makes the wrong reference more misleading than a bad name would be: it
    sends a reader to a real method that does not contain the cleanup
    boundary.

    Caught in review on #67307.

    * docs: tighten the NoticeHandler docblock

    The wording named `CartController::validate_cart()`, the
    `woocommerce_check_cart_items` hook, and described how that caller
    snapshots and restores the queue. All three are outside this class and
    free to change without anyone thinking to update this comment — the
    method name already went stale once, in review, before the change had
    even merged.

    Reduced to the part that belongs here: this method does not clear the
    queue, and callers that need it cleared do it themselves. The contrast
    with `convert_notices_to_exceptions()` stays because that method is in
    this file, which is where the confusion started.

    * docs: correct NoticeHandler error code description

    The parameter documentation for convert_notices_to_wp_errors() claimed the code belonged to thrown exceptions, although the method accumulates notices in a WP_Error object.

    Describe the code as applying to each notice added to WP_Error so the documented contract matches the implementation.

diff --git a/plugins/woocommerce/changelog/fix-notice-handler-docblock b/plugins/woocommerce/changelog/fix-notice-handler-docblock
new file mode 100644
index 00000000000..a70636f5896
--- /dev/null
+++ b/plugins/woocommerce/changelog/fix-notice-handler-docblock
@@ -0,0 +1,4 @@
+Significance: patch
+Type: dev
+
+Correct the NoticeHandler::convert_notices_to_wp_errors() docblock, which claimed it discards notices when it does not.
diff --git a/plugins/woocommerce/src/StoreApi/Utilities/NoticeHandler.php b/plugins/woocommerce/src/StoreApi/Utilities/NoticeHandler.php
index 0bde07df22c..2a9f50b47d8 100644
--- a/plugins/woocommerce/src/StoreApi/Utilities/NoticeHandler.php
+++ b/plugins/woocommerce/src/StoreApi/Utilities/NoticeHandler.php
@@ -44,9 +44,10 @@ class NoticeHandler {
 	 * For example, cart validation processes may add error notices to prevent checkout.
 	 * Since we're not rendering notices at all, we need to catch them and group them in a single WP_Error instance.
 	 *
-	 * This method will discard notices once complete.
+	 * Unlike `convert_notices_to_exceptions()`, this does not clear the notice queue. Callers
+	 * that need it cleared are responsible for doing so.
 	 *
-	 * @param string $error_code Error code for the thrown exceptions.
+	 * @param string $error_code Error code for each notice added to the WP_Error object.
 	 *
 	 * @return \WP_Error The WP_Error object containing all error notices.
 	 */