From 29bb89bc7a894f12d52d1c7559c5bdd2e5bb9cea Mon Sep 17 00:00:00 2001 From: Florian Scholz Date: Mon, 15 Feb 2021 15:38:54 +0100 Subject: [PATCH 1/4] Update contribtion docs for new mixin guideline --- .../en-us/mdn/contribute/changelog/index.html | 6 ++++++ .../howto/write_an_api_reference/index.html | 4 ++-- .../index.html | 21 ++++++++++++------- .../api_landing_page_template/index.html | 7 ------- 4 files changed, 22 insertions(+), 16 deletions(-) diff --git a/files/en-us/mdn/contribute/changelog/index.html b/files/en-us/mdn/contribute/changelog/index.html index 4d8d9b4d985b721..d482ae1b4e328c2 100644 --- a/files/en-us/mdn/contribute/changelog/index.html +++ b/files/en-us/mdn/contribute/changelog/index.html @@ -10,6 +10,12 @@

This document provides a record of MDN content processes, constructs, and best practices that have changed, and when they changed. It is useful to allow regular contributors to check in and see what has changed about the process of creating content for MDN.

+

February 2021

+ +

Documenting mixins

+ +

Previously on MDN, mixins weren't documented consistently. In February, a new guideline was put in place that avoids the abstract, specification-only concept.

+

January 2021

Markup for note and warning boxes

diff --git a/files/en-us/mdn/contribute/howto/write_an_api_reference/index.html b/files/en-us/mdn/contribute/howto/write_an_api_reference/index.html index d373d1f6f2a1a6e..a024c2680f68f0f 100644 --- a/files/en-us/mdn/contribute/howto/write_an_api_reference/index.html +++ b/files/en-us/mdn/contribute/howto/write_an_api_reference/index.html @@ -111,7 +111,7 @@

Interface pages

@@ -275,7 +275,7 @@

Structure of an interface page

  • \{{Non-standard_header}}
    • -
  • Description: the first paragraph of the interface page should provide  a  short concise description of the interface's overarching purpose.  You may also want to include a couple more paragraphs if any additional description is required. Note that if the interface defines a mixin, you shouldn't use the term "Interface" to describe it, but mixin instead — it isn't really a standalone interface as such, but a mixin that adds functionality to multiple other interfaces. Similarly, if the interface is actually a dictionary, you should use that term instead of "interface".
    • +
  • Description: the first paragraph of the interface page should provide  a  short concise description of the interface's overarching purpose.  You may also want to include a couple more paragraphs if any additional description is required. If the interface is actually a dictionary, you should use that term instead of "interface".
  • Inheritance diagram: Use the {{TemplateLink("InheritanceDiagram")}} macro to embed an SVG inheritance diagram for the interface. For most interfaces, you won't need any parameters, but if the inheritance chain is long, you may need to use \{{InheritanceDiagram(600, 120)}} to make room vertically for two rows of boxes.

  • List of properties, List of methods: These sections should be titled  "Properties" and "Methods", and provide links (using the \{{domxref}} macro) to a reference  page for each property/method of that interface, along with a description of what  each one does. These should be marked up using description/definition  lists, which can be created using the  "Definition List", "Definition  Term", and "Definition Description" buttons on the MDN editor toolbar. Each description should be short and concise — one sentence if possible. See the "Referencing other API features with the \{{domxref}} macro" section for a quicker way to create links to other pages.
    diff --git a/files/en-us/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html b/files/en-us/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html index 9198c241dd00f36..a0c41aceebc4c8f 100644 --- a/files/en-us/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html +++ b/files/en-us/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html @@ -91,18 +91,25 @@

    Mixins

    MyInterface includes MyMixin; -

    For documentation purposes, we create a mixin page, with the same structure as an interface page. As they are not true interfaces, the word interface is not used — mixin is used instead.

    +

    For documentation purposes, MDN hides mixins. They are abstract and specification-only constructs. +You can't see them in the Web developer console and it is more useful to know on which real interfaces methods and properties are implemented on.

    -

    Mixin methods and properties are listed in the same way as regular methods and properties:

    +

    If you encounter a mixin in IDL, like HTMLHyperlinkElementUtils, +search for the interfaces that implement the mixin, for example +HTMLAnchorElement, and document the mixin members directly on those interfaces. +

    +

    In practice this means instead of documenting HTMLHyperlinkElementUtils, +docs are added to the concrete interfaces, like HTMLAnchorElement +and HTMLAreaElement.

    + +

    See the following two pages that document HTMLHyperlinkElementUtils.hash accordingly:

    -
    -

    Note: Mixin names do not appear in a Web developer console. We shouldn't show them, but we currently do this as it saves us from duplicating content, which would lead to a maintenance issue. We do this if the mixin is only used in one interface. (Such cases are bugs in the relevant specs. They shouldn't be defined as mixins, but as partial interfaces.)

    -
    +

    For compat data, consult the data guideline for mixins in BCD.

    Old mixin syntax

    diff --git a/files/en-us/mdn/structures/page_types/api_landing_page_template/index.html b/files/en-us/mdn/structures/page_types/api_landing_page_template/index.html index bf8d4018a35050f..2e9b49f01b269fe 100644 --- a/files/en-us/mdn/structures/page_types/api_landing_page_template/index.html +++ b/files/en-us/mdn/structures/page_types/api_landing_page_template/index.html @@ -61,13 +61,6 @@

    Name of API interfaces

    Include a brief description of the interface and what it does here. Include one term and definition for each interface or dictionary.
    -

    Name of API mixins

    - -
    -
    {{domxref("NameOfTheInterface")}}
    -
    Include a brief description of the mixin and what it does here. Include one term and definition for each mixin. If there are no mixins in this API, delete this section.
    -
    -

    Extensions to other interfaces

    The name of interface extends the following APIs, adding the listed features.

    From dd5d009aaa4699cffa54eef02614b2a94a1dec60 Mon Sep 17 00:00:00 2001 From: Florian Scholz Date: Tue, 16 Feb 2021 09:29:18 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Michael[tm] Smith --- .../mdn/contribute/howto/write_an_api_reference/index.html | 2 +- .../information_contained_in_a_webidl_file/index.html | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/mdn/contribute/howto/write_an_api_reference/index.html b/files/en-us/mdn/contribute/howto/write_an_api_reference/index.html index a024c2680f68f0f..4eff58b8f84851a 100644 --- a/files/en-us/mdn/contribute/howto/write_an_api_reference/index.html +++ b/files/en-us/mdn/contribute/howto/write_an_api_reference/index.html @@ -275,7 +275,7 @@

    Structure of an interface page

  • \{{Non-standard_header}}
    • -
  • Description: the first paragraph of the interface page should provide  a  short concise description of the interface's overarching purpose.  You may also want to include a couple more paragraphs if any additional description is required. If the interface is actually a dictionary, you should use that term instead of "interface".
    • +
  • Description: the first paragraph of the interface page should provide a short concise description of the interface's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. If the interface is actually a dictionary, you should use that term instead of "interface".
  • Inheritance diagram: Use the {{TemplateLink("InheritanceDiagram")}} macro to embed an SVG inheritance diagram for the interface. For most interfaces, you won't need any parameters, but if the inheritance chain is long, you may need to use \{{InheritanceDiagram(600, 120)}} to make room vertically for two rows of boxes.

  • List of properties, List of methods: These sections should be titled  "Properties" and "Methods", and provide links (using the \{{domxref}} macro) to a reference  page for each property/method of that interface, along with a description of what  each one does. These should be marked up using description/definition  lists, which can be created using the  "Definition List", "Definition  Term", and "Definition Description" buttons on the MDN editor toolbar. Each description should be short and concise — one sentence if possible. See the "Referencing other API features with the \{{domxref}} macro" section for a quicker way to create links to other pages.
    diff --git a/files/en-us/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html b/files/en-us/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html index a0c41aceebc4c8f..73f00b6e75b372c 100644 --- a/files/en-us/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html +++ b/files/en-us/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html @@ -92,7 +92,7 @@

    Mixins

    MyInterface includes MyMixin;

    For documentation purposes, MDN hides mixins. They are abstract and specification-only constructs. -You can't see them in the Web developer console and it is more useful to know on which real interfaces methods and properties are implemented on.

    +You can't see them in the browser console and it is more useful to know on which real interfaces methods and properties are implemented on.

    If you encounter a mixin in IDL, like HTMLHyperlinkElementUtils, search for the interfaces that implement the mixin, for example From 8d013710ad60dc67b07ab771d109a4bb4801674c Mon Sep 17 00:00:00 2001 From: Florian Scholz Date: Tue, 16 Feb 2021 15:30:27 +0100 Subject: [PATCH 3/4] Make changelog thicker --- files/en-us/mdn/contribute/changelog/index.html | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/files/en-us/mdn/contribute/changelog/index.html b/files/en-us/mdn/contribute/changelog/index.html index d482ae1b4e328c2..97bf305e3c407fc 100644 --- a/files/en-us/mdn/contribute/changelog/index.html +++ b/files/en-us/mdn/contribute/changelog/index.html @@ -14,7 +14,15 @@

    February 2021

    Documenting mixins

    -

    Previously on MDN, mixins weren't documented consistently. In February, a new guideline was put in place that avoids the abstract, specification-only concept.

    +

    Interface mixins in Web IDL are used in specifications to define Web APIs. +For web developers, they aren't observable directly; they act as helpers to avoid repeating API definitions.

    +

    Previously we commonly defined a landing page for a mixin class itself, and put the defined members on subpages underneath it, +before linking to those from the landing pages of the interfaces that implement those mixins. +This was confusing for readers because mixins are spec constructs — you never access the defined members using the mixin classes. +To avoid this confusion we've instead put the pages for members defined on mixins directly under the implementing class pages. +For more details, see the guide page on +how to write an API reference +and the discussion leading to this change in mdn/content#1940.

    January 2021

    From 2ef39bc1a760248c113aaf4e954716cd46c2c1a6 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 16 Feb 2021 14:36:20 +0000 Subject: [PATCH 4/4] copy edit --- files/en-us/mdn/contribute/changelog/index.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/files/en-us/mdn/contribute/changelog/index.html b/files/en-us/mdn/contribute/changelog/index.html index 97bf305e3c407fc..ecce8ffc8240504 100644 --- a/files/en-us/mdn/contribute/changelog/index.html +++ b/files/en-us/mdn/contribute/changelog/index.html @@ -16,13 +16,14 @@

    Documenting mixins

    Interface mixins in Web IDL are used in specifications to define Web APIs. For web developers, they aren't observable directly; they act as helpers to avoid repeating API definitions.

    +

    Previously we commonly defined a landing page for a mixin class itself, and put the defined members on subpages underneath it, before linking to those from the landing pages of the interfaces that implement those mixins. This was confusing for readers because mixins are spec constructs — you never access the defined members using the mixin classes. To avoid this confusion we've instead put the pages for members defined on mixins directly under the implementing class pages. For more details, see the guide page on how to write an API reference -and the discussion leading to this change in mdn/content#1940.

    +and the discussion leading to this change at mdn/content#1940.

    January 2021