Suggestion for updating Composables API documentation

https://vuejs.org/guide/reusability/composables.html#return-values

You have probably noticed that we have been exclusively using ref() instead of reactive() in composables. The recommended convention is for composables to always return a plain, non-reactive object containing multiple refs. This allows it to be destructured in components while retaining reactivity:

While reviewing the documentation for the Composables API, I noticed that the suggested usage of ref() over reactive() might confuse beginners. Specifically, the "Return Values" section recommends using ref() over reactive() and returning a non-reactive object containing multiple refs. However, this may mislead beginners into thinking that reactive() is useless in Composables API.

In reality, we should freely choose whether to use ref() or reactive() depending on the need. reactive() is more suitable for managing objects or collections that contain multiple properties. While the article suggests using ref() mainly as it prevents the loss of reactivity when destructuring the object. Therefore, I suggest updating the documentation to clarify that the reactive() function is also important in the Composables API.

Furthermore, in writing Composables functions, we can use a reactive object and wrap it with a plain object while returning it, which still maintains reactivity. It is essential to ensure that the returned object retains reactivity even when destructured.

In conclusion, I suggest updating the documentation about using ref() and reactive() in Composables API to avoid any potential misunderstandings for beginners.

Thank you!

Open the linked Composables API documentation and read the Return Values section, including its discussion of ref() and reactive(). Update the explanation so beginners understand when either API is appropriate and how returned objects preserve reactivity when destructured; the section should no longer imply that reactive() is generally unsuitable for composables.