diff --git a/files/en-us/mdn/contribute/changelog/index.html b/files/en-us/mdn/contribute/changelog/index.html index 4d8d9b4d985b721..ecce8ffc8240504 100644 --- a/files/en-us/mdn/contribute/changelog/index.html +++ b/files/en-us/mdn/contribute/changelog/index.html @@ -10,6 +10,21 @@

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

+ +

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 at mdn/content#1940.

+

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..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 @@ -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..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 @@ -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 browser 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.