From 881e0a3d363b6a1590925ea3649bde30e6cbf279 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Philip=20J=C3=A4genstedt?= <philip@foolip.org>
Date: Fri, 23 Apr 2021 22:40:18 +0200
Subject: [PATCH] Editorial: simplify the example on default toJSON()

This example was adapted from a previous one in
https://github.com/heycam/webidl/pull/433, but things are much simpler
now and the example makes it seem more complicated than it really is.

Make the points inheritance and mixins separately.

This also fixes the order of attributes on the returned JSON object,
which was wrong the original example. The attributes of the base
interface should be included first. Reverse the inheritance order in
the example to make this clearer, matching `interface B : A` in two
other examples.

Fixes https://github.com/heycam/webidl/issues/979.
---
 index.bs | 91 +++++++++++++++++++++++++-------------------------------
 1 file changed, 40 insertions(+), 51 deletions(-)

diff --git a/index.bs b/index.bs
index 3e226f63..74c86308 100644
--- a/index.bs
+++ b/index.bs
@@ -12090,84 +12090,73 @@ A [=regular operation=] that does not [=have default method steps=] must not be
 
 <div class=example id=example-tojson-default-inheritance-and-mixins>
 
-    The following [=IDL fragment=] defines a number of [=interfaces=],
-    which are [=inherited interfaces=] of <code class="idl">A</code>,
-    and [=interface mixins=], which are [=included=] by <code class="idl">A</code> or
-    by <code class="idl">A</code>'s [=inherited interfaces=],
-    as show in the below inheritance tree.
-
-    <pre>
-             C* - M4
-             |
-             B - M3
-             |
-        M1 - A - M2*
-    </pre>
-
-    [=Interfaces=] and [=interface mixins=] marked with an asterisk ("*")
-    declare a <code>toJSON</code> [=operation=]
-    with a [{{Default}}] [=extended attribute=].
+    Only [=regular attributes=] of [=interfaces=] that declare a <code>toJSON</code> operation with
+    a [{{Default}}] [=extended attribute=] are included, even if an [=inherited interface=] declares
+    such a <code>toJSON</code> operation. For example, consider the following [=IDL fragment=]:
 
     <pre class=webidl>
         [Exposed=Window]
-        interface A : B {
+        interface A {
+          [Default] object toJSON();
           attribute DOMString a;
         };
 
         [Exposed=Window]
-        interface B : C {
+        interface B : A {
           attribute DOMString b;
         };
 
         [Exposed=Window]
-        interface C {
+        interface C : B {
           [Default] object toJSON();
           attribute DOMString c;
         };
+    </pre>
 
-        interface mixin M1 {
-          attribute DOMString m1;
-        };
-
-        interface mixin M2 {
-          [Default] object toJSON();
-          attribute DOMString m2;
-        };
-
-        interface mixin M3 {
-          attribute DOMString m3;
-        };
-
-        interface mixin M4 {
-          attribute DOMString m4;
-        };
+    Calling the <code>toJSON()</code> method of an object implementing interface
+    <code class="idl">C</code> defined above would return the following JSON object:
 
-        A includes M1;
-        A includes M2;
-        B includes M3;
-        C includes M4;
+    <pre highlight=json>
+    {
+        "a": "...",
+        "c": "..."
+    }
     </pre>
 
-    Calling the <code>toJSON()</code> method of an object
-    implementing interface <code class="idl">A</code> defined above
-    would return the following JSON object:
+    Calling the <code>toJSON()</code> method of an object implementing interface
+    <code class="idl">A</code> (or <code class="idl">B</code>) defined above would return:
 
     <pre highlight=json>
     {
-        "a": "...",
-        "m1": "...",
-        "m2": "...",
-        "c": "...",
-        "m4": "..."
+        "a": "..."
     }
     </pre>
 
-    An object implementing interface <code class="idl">B</code> would return:
+    A <code>toJSON</code> operation can also be declared on an [=interface mixin=] (or
+    [=partial interface=]) and is equivalent to declaring it on the original [=interface=]. For
+    example, consider the following [=IDL fragment=]:
+
+    <pre class=webidl>
+        [Exposed=Window]
+        interface D {
+          attribute DOMString d;
+        };
+
+        interface mixin M {
+          [Default] object toJSON();
+          attribute DOMString m;
+        };
+
+        D includes M;
+    </pre>
+
+    Calling the <code>toJSON()</code> method of an object implementing interface
+    <code class="idl">D</code> defined above would return:
 
     <pre highlight=json>
     {
-        "c": "...",
-        "m4": "..."
+        "d": "...",
+        "m": "..."
     }
     </pre>
 </div>