chore: comments [ci skip]

packages/reactivity/src/reactive.ts

@@ -59,6 +59,28 @@ function getTargetType(value: Target) {
 // only unwrap nested ref
 type UnwrapNestedRefs<T> = T extends Ref ? T : UnwrapRef<T>
 
+/**
+ * Creates a reactive copy of the original object.
+ *
+ * The reactive conversion is "deep"—it affects all nested properties. In the
+ * ES2015 Proxy based implementation, the returned proxy is **not** equal to the
+ * original object. It is recommended to work exclusively with the reactive
+ * proxy and avoid relying on the original object.
+ *
+ * A reactive object also automatically unwraps refs contained in it, so you
+ * don't need to use `.value` when accessing and mutating their value:
+ *
+ * ```js
+ * const count = ref(0)
+ * const obj = reactive({
+ *   count
+ * })
+ *
+ * obj.count++
+ * obj.count // -> 1
+ * count.value // -> 1
+ * ```
+ */
 export function reactive<T extends object>(target: T): UnwrapNestedRefs<T>
 export function reactive(target: object) {
   // if trying to observe a readonly proxy, return the readonly version.
@@ -73,9 +95,11 @@ export function reactive(target: object) {
   )
 }
 
-// Return a reactive-copy of the original object, where only the root level
+/**
-// properties are reactive, and does NOT unwrap refs nor recursively convert
+ * Return a shallowly-reactive copy of the original object, where only the root
-// returned properties.
+ * level properties are reactive. It also does not auto-unwrap refs (even at the
+ * root level).
+ */
 export function shallowReactive<T extends object>(target: T): T {
   return createReactiveObject(
     target,
@@ -107,6 +131,10 @@ export type DeepReadonly<T> = T extends Builtin
                   ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
                   : Readonly<T>
 
+/**
+ * Creates a readonly copy of the original object. Note the returned copy is not
+ * made reactive, but `readonly` can be called on an already reactive object.
+ */
 export function readonly<T extends object>(
   target: T
 ): DeepReadonly<UnwrapNestedRefs<T>> {
@@ -118,10 +146,12 @@ export function readonly<T extends object>(
   )
 }
 
-// Return a reactive-copy of the original object, where only the root level
+/**
-// properties are readonly, and does NOT unwrap refs nor recursively convert
+ * Returns a reactive-copy of the original object, where only the root level
-// returned properties.
+ * properties are readonly, and does NOT unwrap refs nor recursively convert
-// This is used for creating the props proxy object for stateful components.
+ * returned properties.
+ * This is used for creating the props proxy object for stateful components.
+ */
 export function shallowReadonly<T extends object>(
   target: T
 ): Readonly<{ [K in keyof T]: UnwrapNestedRefs<T[K]> }> {