Documentation clarification needed for onWatcherCleanup in async contexts

[Edwinroman30]

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+