Documentation clarification needed for onWatcherCleanup in async contexts

Documentation clarification needed for onWatcherCleanup in async contexts

Issue description

The current documentation for onWatcherCleanup mentions an important constraint but could benefit from clearer examples showing proper vs. improper usage in async contexts.

Current documentation states:

Note that onWatcherCleanup is only supported in Vue 3.5+ and must be called during the synchronous execution of a watchEffect effect function or watch callback function: you cannot call it after an await statement in an async function.

Proposed improvement

Add explicit examples showing both correct usage and incorrect usage patterns to help developers understand the timing constraint. This would help prevent common mistakes when working with async operations.

Example to add

// ✅ Correct: Called during synchronous portion
watch(id, (newId) => {
  const controller = new AbortController()
  
  // Register cleanup BEFORE any async operations
  onWatcherCleanup(() => {
    controller.abort()
  })
  
  // Async operation happens after registering cleanup
  fetch(`/api/${newId}`, { signal: controller.signal })
    .then(response => {
      // handle response
    })
})

// ❌ Incorrect: Called after await
watch(id, async (newId) => {
  const controller = new AbortController()
  
  // BAD: This awaits before registering cleanup
  await fetch(`/api/${newId}`, { signal: controller.signal })
  
  // This won't work properly - it's after an await
  onWatcherCleanup(() => {
    controller.abort() // This cleanup may not be properly associated with the watcher
  })
})

Why this matters

Without clear examples, developers might inadvertently violate this constraint, leading to cleanup functions that don't execute as expected. This is especially important for resource cleanup scenarios like canceling network requests, removing event listeners, or clearing timers.

Additional context

This clarification would be valuable in the Watchers section of the Vue.js documentation where onWatcherCleanup is discussed.

• https://vuejs.org/guide/essentials/watchers.html

Environment

• Vue version: 3.5+

Open the Watchers section at the linked Vue documentation page and find the existing onWatcherCleanup guidance. Compare the current explanation with the issue's correct and incorrect async examples, then add clear examples of registering cleanup before await and explain the constraint. Done means the timing rule and both usage patterns are understandable to readers.