defineModel description in guide and API could be improved to be more precise.

[alex-springer-sr]

From the Guide basic usage

The value returned by defineModel() is a ref. It can be accessed and mutated like any other ref, except that it acts as a two-way binding between a parent value and a local one:

Its .value is synced with the value bound by the parent v-model;
When it is mutated by the child, it causes the parent bound value to be updated as well.

From the Guide under the hood:

defineModel is a convenience macro. The compiler expands it to the following:

A prop named modelValue, which the local ref's value is synced with;
An event named update:modelValue, which is emitted when the local ref's value is mutated.

While this is true for primitives it leads to IMO quite serious mistakes when people want to use objects or arrays as models.
I had this happen at a project i am working on where we now have quite a lot of places mutating props because developers assumed the update event is emitted when a property of the object or element of an array is updated.

I would suggest updating the text to state that the ref is a shallow ref.
In the under the hood part i would appreciate an explanation of what is actually being done under the hood ( i tried to figure it out, but could not understand the code).

I am happy to create a PR or help further flesh this out, but would appreciate some feedback first.

[alex-springer-sr]

Also the following discussion can provide info on how to better document this:
https://github.com/orgs/vuejs/discussions/10538

[alex-springer-sr]

Found the source code that actually creates the functionality behind defineModel macro :
https://github.com/vuejs/core/blob/main/packages/runtime-core/src/helpers/useModel.ts

I will create a PR for updating the docs once i get to it.