Add a note about why dialog uses show/close

source

@@ -58899,7 +58899,7 @@ interface <dfn interface>HTMLDialogElement</dfn> : <span>HTMLElement</span> {
 
   </div>
 
-  <div class="note">
+  <div class="note" id="note-dialog-remove-open-attribute">
    <p>Removing the <code data-x="attr-dialog-open">open</code> attribute will usually hide the
    dialog. However, doing so has a number of strange additional consequences:
 
@@ -59102,6 +59102,45 @@ interface <dfn interface>HTMLDialogElement</dfn> : <span>HTMLElement</span> {
   the last value to which it was set. On setting, it must be set to the new value. When the element
   is created, it must be set to the empty string.</p>
 
+  </div>
+
+  <div class="note" id="note-dialog-method-names">
+   <p>The reason we use show/close as the verbs for dialog elements, as opposed to verb pairs that
+   are more commonly thought of as English antonyms such as show/hide or open/close, is due to the
+   following constraints:</p>
+
+   <ul>
+    <li><p>Hiding a dialog is different from closing one. Closing a dialog gives it a return value,
+    fires an event, unblocks the page for other dialogs, and so on. Whereas hiding a dialog is a
+    purely visual property, and is something you can already do with the <code
+    data-x="attr-hidden">hidden</code> attribute or by removing the <code
+    data-x="attr-dialog-open">open</code> attribute. (See also the <a
+    href="#note-dialog-remove-open-attribute">note above</a> about removing the <code
+    data-x="attr-dialog-open">open</code> attribute, and how hiding the dialog in that way is
+    generally not desired.)</p></li>
+
+    <li><p>Showing a dialog is different from opening one. Opening a dialog consists of creating
+    and showing that dialog (similar to how <code data-x="dom-open">window.open()</code> both
+    creates and shows a new window). Whereas showing the dialog is the process of taking a
+    <code>dialog</code> element that is already in the DOM, and making it interactive and visible
+    to the user.</p></li>
+
+    <li><p>If we were to have a <code data-x="">dialog.open()</code> method despite the above, it
+    would conflict with the <code data-x="dom-dialog-open">dialog.open</code> property.</p></li>
+   </ul>
+
+   <p>Furthermore, a <a
+   href="https://lists.whatwg.org/pipermail/whatwg-whatwg.org/2013-December/041799.html">survey</a>
+   of many other UI frameworks contemporary to the original design of the <code>dialog</code>
+   element made it clear that the show/close verb pair was reasonably common.</p>
+
+   <p>In summary, it turns out that the implications of English verbs, and how they are used in
+   technology contexts, mean that paired actions such as showing and closing a dialog are not
+   always expressible as antonyms.</p>
+  </div>
+
+  <div w-nodev>
+
   <hr>
 
   <p id="canceling-dialogs"><strong>Canceling dialogs</strong>: When <code>Document</code> is