From 301958d2df080590b3939776e20f32505532b8ef Mon Sep 17 00:00:00 2001
From: skirtle <65301168+skirtles-code@users.noreply.github.com>
Date: Wed, 7 Jul 2021 06:36:03 +0100
Subject: [PATCH] docs: update the API entries for mixins and extends to
 reference setup

---
 src/api/options-composition.md | 48 ++++++++++++++++++++++++++++++----
 1 file changed, 43 insertions(+), 5 deletions(-)

diff --git a/src/api/options-composition.md b/src/api/options-composition.md
index ac8507012f..fbb2c324de 100644
--- a/src/api/options-composition.md
+++ b/src/api/options-composition.md
@@ -10,11 +10,15 @@
 
   Mixin hooks are called in the order they are provided, and called before the component's own hooks.
 
+  :::info
+  In Vue 2, mixins were the primary mechanism for creating reusable chunks of component logic. While mixins continue to be supported in Vue 3, the [composition API](/guide/composition-api-introduction.html) is now the preferred approach for code reuse between components.
+  :::
+
 - **Example:**
 
   ```js
   const mixin = {
-    created: function() {
+    created() {
       console.log(1)
     }
   }
@@ -34,26 +38,60 @@
 
 ## extends
 
-- **Type:** `Object | Function`
+- **Type:** `Object`
 
 - **Details:**
 
-  Allows declaratively extending another component (could be either a plain options object or a constructor). This is primarily intended to make it easier to extend between single file components.
+  Allows one component to extend another, inheriting its component options.
+
+  From an implementation perspective, `extends` is almost identical to `mixins`. The component specified by `extends` will be treated as though it were the first mixin.
+
+  However, `extends` and `mixins` express different intents. The `mixins` option is primarily used to compose chunks of functionality, whereas `extends` is primarily concerned with inheritance.
 
-  This is similar to `mixins`.
+  As with `mixins`, any options will be merged using the relevant merge strategy.
 
 - **Example:**
 
   ```js
   const CompA = { ... }
 
-  // extend CompA without having to call `Vue.extend` on either
   const CompB = {
     extends: CompA,
     ...
   }
   ```
 
+- **Usage with `setup`:**
+
+  Using `extends` loses the explicitness of `setup`, so combining the two approaches is usually undesirable. However, it can be useful in cases where the extending component contains very little code and is almost identical to the extended component.
+
+  `extends` will not inherit the `setup` function from the extended component but it can be copied across manually:
+
+  ```js
+  const CompA = { ... }
+
+  const CompB = {
+    extends: CompA,
+    setup: CompA.setup,
+    ...
+  }
+  ```
+
+  If you need to add your own `setup` function you can call the inherited `setup` function at an appropriate point:
+
+  ```js
+  const CompA = { ... }
+
+  const CompB = {
+    extends: CompA,
+    setup (props, context) {
+      const inheritedProperties = CompA.setup(props, context)
+      ...
+    },
+    ...
+  }
+  ```
+
 ## provide / inject
 
 - **Type:**