explain how multiple inheritance works in >=3.3.0 (#66)

Author: hegemonic

content/en/tags-augments.md

@@ -1,6 +1,6 @@
 ---
 tag: augments
-description: This object adds onto a parent object.
+description: Indicate that a symbol inherits from, ands adds to, a parent symbol.
 synonyms:
     - extends
 related:
@@ -17,22 +17,21 @@ related:
 
 ## Overview
 
-The @augments or @extends tag marks a symbol as augmenting another symbol.
+The `@augments` or` @extends` tag indicates that a symbol inherits from, and potentially adds to, a
+parent symbol. You can use this tag to document both class-based and prototype-based inheritance.
 
-While current versions of JavaScript don't allow classes or subclasses in the same way that
-class-based languages like Java do, many programmers choose to think of their code structure in
-these terms. For this purpose JSDoc provides the @class and @extends tags. If you wish to express a
-similar relationship between two symbols, but don't wish to promote the classical analogy, you can
-use the @constructor and @augments tags instead.
+In JSDoc 3.3.0 and later, if a symbol inherits from multiple parents, and both parents have
+identically named members, JSDoc uses the documentation from the last parent that is listed in the
+JSDoc comment.
 
 
 ## Examples
 
-In the example below I wish to document the fact that Ducks are a specialised form of Animal:
-meaning that Duck instances are like Animal instances which have been augmented with additional
-properties.
+In the following example, the `Duck` class is defined as a subclass of `Animal`. `Duck` instances
+have the same properties as `Animal` instances, as well as a `speak` method that is unique to `Duck`
+instances.
 
-{% example "Documenting a class/subclass type of relationship." %}
+{% example "Documenting a class/subclass relationship" %}
 
 ```js
 /**
@@ -47,23 +46,71 @@ function Animal() {
  * @constructor
  * @augments Animal
  */
-function Duck() {
-}
+function Duck() {}
 Duck.prototype = new Animal();
 
 /** What do ducks say? */
 Duck.prototype.speak = function() {
     if (this.alive) {
         alert('Quack!');
     }
-}
+};
 
 var d = new Duck();
 d.speak(); // Quack!
-d.alive = false; // dead duck?
-d.speak();
+d.alive = false;
+d.speak(); // (nothing)
 ```
 {% endexample %}
 
-A related pattern can be documented with the @mixin and @mixes tags. Or, if the augmented symbol is
-only reusing one or two members of another symbol, you may find the @borrows tag more convenient.
+In the following example, the `Duck` class inherits from both the `Flyable` and `Bird` classes, both
+of which define a `takeOff` method. Because the documentation for `Duck` lists `@augments Bird`
+last, JSDoc automatically documents `Duck#takeOff` using the comment from `Bird#takeOff`.
+
+{% example "Multiple inheritance with duplicated method names" %}
+
+```js
+/**
+ * Abstract class for things that can fly.
+ * @class
+ */
+function Flyable() {
+    this.canFly = true;
+}
+
+/** Take off. */
+Flyable.prototype.takeOff = function() {
+    // ...
+};
+
+/**
+ * Abstract class representing a bird.
+ * @class
+ */
+function Bird(canFly) {
+    this.canFly = canFly;
+}
+
+/** Spread your wings and fly, if possible. */
+Bird.prototype.takeOff = function() {
+    if (this.canFly) {
+        this._spreadWings()
+            ._run()
+            ._flapWings();
+    }
+};
+
+/**
+ * Class representing a duck.
+ * @class
+ * @augments Flyable
+ * @augments Bird
+ */
+function Duck() {}
+
+// Described in the docs as "Spread your wings and fly, if possible."
+Duck.prototype.takeOff = function() {
+    // ...
+};
+```
+{% endexample %}

index.html

@@ -68,7 +68,7 @@ <h2 id="tag-dictionary">Tag Dictionary</h2>
       <dt><a href="tags-alias.html">@alias</a></dt>
       <dd>Treat a member as if it had a different name.</dd>
       <dt><a href="tags-augments.html">@augments</a> (synonyms: @extends)</dt>
-      <dd>This object adds onto a parent object.</dd>
+      <dd>Indicate that a symbol inherits from, ands adds to, a parent symbol.</dd>
       <dt><a href="tags-author.html">@author</a></dt>
       <dd>Identify the author of an item.</dd>
       <dt><a href="tags-borrows.html">@borrows</a></dt>

tags-augments.html

@@ -4,7 +4,7 @@
 
 <head>
   <meta charset="utf-8">
-  <meta name="description" content="This object adds onto a parent object.">
+  <meta name="description" content="Indicate that a symbol inherits from, ands adds to, a parent symbol.">
   <title>Use JSDoc: @augments</title>
   <link rel="stylesheet" href="styles/usejsdoc.css">
   <link rel="stylesheet" href="styles/prettify.css">
@@ -48,16 +48,16 @@ <h2 id="syntax">Syntax</h2>
     <p><code>@augments &lt;namepath&gt;</code>
     </p>
     <h2 id="overview">Overview</h2>
-    <p>The @augments or @extends tag marks a symbol as augmenting another symbol.</p>
-    <p>While current versions of JavaScript don&#39;t allow classes or subclasses in the same way that class-based languages like Java do, many programmers choose to
-      think of their code structure in these terms. For this purpose JSDoc provides the @class and @extends tags. If you wish to express a similar relationship between
-      two symbols, but don&#39;t wish to promote the classical analogy, you can use the @constructor and @augments tags instead.</p>
+    <p>The <code>@augments</code> or<code>@extends</code> tag indicates that a symbol inherits from, and potentially adds to, a parent symbol. You can use this tag
+      to document both class-based and prototype-based inheritance.</p>
+    <p>In JSDoc 3.3.0 and later, if a symbol inherits from multiple parents, and both parents have identically named members, JSDoc uses the documentation from the
+      last parent that is listed in the JSDoc comment.</p>
     <h2 id="examples">Examples</h2>
-    <p>In the example below I wish to document the fact that Ducks are a specialised form of Animal: meaning that Duck instances are like Animal instances which have
-      been augmented with additional properties.
+    <p>In the following example, the <code>Duck</code> class is defined as a subclass of <code>Animal</code>. <code>Duck</code> instances have the same properties as
+      <code>Animal</code> instances, as well as a <code>speak</code> method that is unique to <code>Duck</code> instances.
     </p>
     <figure>
-      <figcaption>Documenting a class/subclass type of relationship.</figcaption><pre class="prettyprint lang-js"><code>/**
+      <figcaption>Documenting a class/subclass relationship</figcaption><pre class="prettyprint lang-js"><code>/**
  * @constructor
  */
 function Animal() {
@@ -69,25 +69,69 @@ <h2 id="examples">Examples</h2>
  * @constructor
  * @augments Animal
  */
-function Duck() {
-}
+function Duck() {}
 Duck.prototype = new Animal();
 
 /** What do ducks say? */
 Duck.prototype.speak = function() {
     if (this.alive) {
         alert('Quack!');
     }
-}
+};
 
 var d = new Duck();
 d.speak(); // Quack!
-d.alive = false; // dead duck?
-d.speak();
+d.alive = false;
+d.speak(); // (nothing)
+</code></pre>
+    </figure>
+    <p>In the following example, the <code>Duck</code> class inherits from both the <code>Flyable</code> and <code>Bird</code> classes, both of which define a <code>takeOff</code>      method. Because the documentation for <code>Duck</code> lists <code>@augments Bird</code> last, JSDoc automatically documents <code>Duck#takeOff</code> using
+      the comment from <code>Bird#takeOff</code>.</p>
+    <figure>
+      <figcaption>Multiple inheritance with duplicated method names</figcaption><pre class="prettyprint lang-js"><code>/**
+ * Abstract class for things that can fly.
+ * @class
+ */
+function Flyable() {
+    this.canFly = true;
+}
+
+/** Take off. */
+Flyable.prototype.takeOff = function() {
+    // ...
+};
+
+/**
+ * Abstract class representing a bird.
+ * @class
+ */
+function Bird(canFly) {
+    this.canFly = canFly;
+}
+
+/** Spread your wings and fly, if possible. */
+Bird.prototype.takeOff = function() {
+    if (this.canFly) {
+        this._spreadWings()
+            ._run()
+            ._flapWings();
+    }
+};
+
+/**
+ * Class representing a duck.
+ * @class
+ * @augments Flyable
+ * @augments Bird
+ */
+function Duck() {}
+
+// Described in the docs as "Spread your wings and fly, if possible."
+Duck.prototype.takeOff = function() {
+    // ...
+};
 </code></pre>
     </figure>
-    <p>A related pattern can be documented with the @mixin and @mixes tags. Or, if the augmented symbol is only reusing one or two members of another symbol, you may
-      find the @borrows tag more convenient.</p>
     <h2 id="related-links">Related Links</h2>
     <ul>
       <li>