Fix linting errors "Expected h2#Examples for data.examples"

[Elchi3]

We need to update the JS docs to have example sections. This affects quite some pages:

---

20 errors javascript-method/data.examples/expected-heading
17 errors javascript-constructor/data.examples/expected-heading
15 errors javascript-language-feature/data.examples/expected-heading
9 errors javascript-class/data.examples/expected-heading
8 errors javascript-property/data.examples/expected-heading
6 errors javascript-namespace/data.examples/expected-heading

= 75

[Elchi3]

Okay, I've done some good progress on this and brought the issue number down to 30 (from 75). The remaining work can be put in 3 categories:

Single page describing multiple features

• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Class_fields (we already said that this page needs splitting into two)
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators (Will is doing this)
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Assignment_Operators (Florian taking this one)
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Operators (Will is doing this)
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_Operators (taken by Florian)
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_Operators
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer

Structural rewrite needed to have an Examples section

• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Property_Accessors
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this

Examples entirely missing

• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/@@toPrimitive
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/Locale
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/NaN
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toLocaleString
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/any
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/valueOf
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/replace
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/search
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/split
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance/Instance
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module/Module

[Elchi3]

For the category "Single page describing multiple features", I need some advise on what to do. These are operator pages describing multiple operators on a single page and thus they don't naturally follow our recipe.

For "Examples entirely missing", I will see how it goes this week, but a helping hand would be appreciated in order to reach the sprint goal.

[Elchi3]

@chrisdavidmills this is the issue about the remaining example section fixes that is needed in the JS docs. The linter complains about WebAssembly Module and Instance pages. These have no "Examples" sections at all. If you have an idea of what to add there, that would be great!

[wbamberg]

This is great work Florian!

About "single page describing multiple features". Let's look at each one.

Arithmetic operators

https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators

This clearly describes multiple language features. Its structure is like:

H2 item1
  H3 Syntax
  H3 Examples
H2 item2
  H3 Syntax
  H3 Examples
...

I could think of three options here:

1. introduce a new page type for this. I don't think we should do this. It's not a different kind of thing, it's a different way we have chosen to present the same kind of thing.
2. separate pages for the different operators. Although it's quite disruptive, I think this is technically the right thing to do, for the following reasons:
   • Some operators get their own page (e.g. in) and some don't. Why?
   • The BCD table for the "Arithmetic operators" page doesn't have a "basic support" line (and can't, because what would it mean?). If it weren't for the fact that these operators live under the same branch of the tree, we would need to have separate BCD tables, as we do, problematically, for the CSS gap property - and in fact because the gap "context" subfeatures live under the css.properties.gap node, we could do exactly the same thing there as we do here.
   • Imagining things from a structured content perspective, it seems likely we want separate "items" for the different arithmetic operators. Otherwise someone wanting to get "all the JS language features" would get some operators on their own (e.g. in) and some lumped together.
3. decide we don't want to deal with this now, and invert the structure of this page into:

H2 Syntax
  H3 item1
  H3 item2
H2 Examples
  H3 item1
  H3 item2

Assignment operators

https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Assignment_Operators

This also describes multiple items although the structure is a bit different:

H2 Syntax
H2 Description
  H3 item1
    H4 Syntax
    H4 Examples
  H3 item2
    H4 Syntax
    H4 Examples

It's particularly weird because it has two sets of "Syntax" sections, one at the top level and one that's a series of H4's under H2#Description.

I think the same options apply to this page as to "Arithmetic operators". If we were to go with option 3 it seems we could have something like:

H2 Syntax
  H3 item1
  H3 item2
H2 Description
  H3 item1
  H3 item2
H2 Examples
  H3 item1
  H3 item2

Comparison operators

https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Operators

These have a somewhat similar structure to "Assignment operators":

anonymous prose after interactive example
H2 Equality operators
  H3 item1
    H4 Syntax
    H4 Examples
  H3 item2
    H4 Syntax
    H4 Examples
H2 Relational operators
  H3 item1
    H4 Syntax
    H4 Examples
  H3 item2
    H4 Syntax
    H4 Examples

It's a little different because the page has a top-level separation between equality operators and relational operators. If we want to go with option 3 above we could do something like:

H2 Syntax
  H3 item1
  H3 item2
H2 Description
  contents of anonymous prose section, and anything else useful about equality versus relational operators
H2 Examples
   H3 item1
   H3 item2

Destructuring assignment

https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment

The one is quite different:

H2 Syntax
H2 Description
H2 Array destructuring
H2 Object destructuring

To me the last two sections above, "H2 Array destructuring" and "H2 Object destructuring" contain examples. So I'd just move them into a new H2#Examples section. One question is whether to keep those "Array destructuring" and "Object destructuring" sections:

H2 Syntax
H2 Description
H2 Examples
  H3 Array destructuring
    H4 example1
    H4 example2
H2 Object destructuring
    H4 example3
    H4 example4

...or to flatten the examples:

H2 Syntax
H2 Description
H2 Examples
  H3 example1
  H3 example2
  H3 example3
  H3 example4

I think flattening them would be preferable, since we kind of want items under H2#Examples to be individual examples (although we don't lint for this). But I think not flattening would be OK in this situation too.

Logical operators

https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_Operators

This page covers three operators (&&, ||, !), and looks like:

H2 Description
    H3 Short-circuit evaluation
    H3 Operator precedence
    H3 Logical AND (&&)   *
    H3 Logical OR (||)        *
    H3 Logical NOT (!)       *
    H3 Conversion rules for booleans
    H3 Removing nested parentheses

The three that I've marked look like examples, the rest look fine in H2#Description. So we could do:

H2 Description
    H3 Short-circuit evaluation
    H3 Operator precedence
    H3 Conversion rules for booleans
    H3 Removing nested parentheses
H2 Examples
    H3 Logical AND (&&)
    H3 Logical OR (||)
    H3 Logical NOT (!)

Note that there's no H2#Syntax in this page. We could extract that out of H2#Description though.

Object initializer

https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer

This doesn't seem to cover multiple operators?

But it has a structure like:

H2 Syntax
H2 Description
  H3 Creating objects
  H3 Accessing properties
  H3 Property definitions
...etc

It looks like this is just missing an H2#Examples section.

(It's interesting to note that (and this applies to some of the other pages too) the style of documentation here is very example-driven. Our page structure separates "description" and "examples" at the top level, which moves examples further away from descriptive prose, and this is a drawback. On the other hand, having examples corralled under an H2 makes it easier for people to find an example of the thing they are looking for.)

[chrisdavidmills]

WebAssembly examples added:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module#Examples
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module/Module#Examples
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance#Examples
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance/Instance#Examples

[wbamberg]

Thanks for adding these Chris! For future reference: the linter expects examples under H2#Examples to live under an H3 describing each example, even if there's only one of them: https://github.com/mdn/stumptown-content/blob/master/project-docs/linter-spec.md#dataexamples.

I have added H3s here, and the linter is now happy with the WebAssembly docs. But you might like to check the H3s I have added.

[chrisdavidmills]

Cheers for the explanation Will. I've tweaked them a little bit. I've also added another Promise.any() example, as I had one written from a while ago.

I'll get on with some more JS examples tomorrow.

[ddbeck]

Looking at Intl and Reflect, do I understand correctly that we intend to require examples for namespaces? The only namespace I could find with examples is Atomics, which does a sort of catch-all demonstration of many methods.

Or maybe a better question is, should I open an issue for this?

[Elchi3]

The only namespace I could find with examples is Atomics, which does a sort of catch-all demonstration of many methods.

Oh yes, I forgot to ask about this. I only added this catch-all example demonstration recently when the linter complained to me. I like it, but of course we could also say that namespaces need no example sections.

[ddbeck]

we could also say that namespaces need no example sections

OK. I opened #464 to consider it. I'm not sure if we should, but there's a good place to take that conversation, at least.

---

Also, I added examples for these two:

• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/valueOf
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/@@toPrimitive

If someone else wants to take a quick look at them, I'd appreciate it. Given the suggestion that you'll probably never call the methods directly, the examples seem a bit contrived. Plus, I didn't really know anything about Symbols before today. 🤷‍♂️

[chrisdavidmills]

@ddbeck I'd say these symbol examples look OK. Compared to regular JS, accessing them is a little strange, and you'd rarely have much cause to use them in a real app. So I think a light example of how to access those values is fine for now.

I did a whole bunch of these on Friday, as you can see from the checkboxes. I'm gonna do some more today too.

[chrisdavidmills]

I just did an example for Reflect, which was perfectly fine.

but then I tried doing an example for https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/search#Examples — after racking my brains for a while, I just ended up copying the interactive example. It really is quite hard to think up anything useful for each Symbols. But then, it probably isn't a very good idea to repeat the Interactive Example.

Any thoughts on what might be better here?

[Elchi3]

Any thoughts on what might be better here?

So, I think Symbols are used to implement custom behavior for some built-in methods or operators. In this case it is to customize string search. So, I've modified the example to show how to implement a case insensitive search. Not sure if useful, but it demonstrates the mechanics some more, I think?
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/search#Examples

[chrisdavidmills]

So, I think Symbols are used to implement custom behavior for some built-in methods or operators. In this case it is to customize string search. So, I've modified the example to show how to implement a case insensitive search.

Thanks Florian! This certainly makes it clearer to me how they could be used. I'll have a go at doing another one in a similar fashion (i.e. copying the interactive example, and extending it a bit).

[chrisdavidmills]

Symbol.split example done, which means all the examples are now complete: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/split#Examples

[Elchi3]

I've done the page split for https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_Operators. It now redirects to https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_Operators

The separate pages I've created are here:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_AND
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_OR
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_NOT

BCD: mdn/browser-compat-data#6235
IE: mdn/interactive-examples#1597

So, here the split involved 3 operators and took me a little less than 2 hours.

Also updated https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators#Logical to link to the new pages.

[wbamberg]

I've created separate pages for all the arithmetic operators:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Addition
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Subtraction
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Division
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Multiplication
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Remainder
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Exponentiation
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Increment
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Decrement
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Unary_negation
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Unary_plus

I've filed mdn/browser-compat-data#6246 for the BCD. I ran out of time to do interactive examples, that'll have to wait till tomorrow.

[wbamberg]

I'm working on the comparison operators now.

I've written up pages for the equality operators:
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Inequality
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Strict_inequality

No BCD or interactive examples yet. I'd love some review, because I've written quite a bit of new content here and it is tricky! Note that this is intended to replace most of the content currently in https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Operators. But if I have mangled anything there or omitted important stuff, that would be good to know.

[Elchi3]

I think this looks great, Will! I like the example sections a lot. I helps me to differentiate these a lot better. Nice work!

It would probably be good to (prominently) link to https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators#Comparison from these pages for those who want to compare the comparison operators (ha!) all at once.

[wbamberg]

I've written up pages for the other four comparison operators:

https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Greater_than
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Greater_than_or_equal
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Less_than
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Less_than_or_equal

...and filed a PR for the BCD.

[Elchi3]

For arithmetic operators, I've redirected https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators to https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators and updated the links on https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators.

I've also updated https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators.

The BCD will ship this week, but I marked the task for arithmetic operators as complete already here.

Thanks for your help with this, Will! I really like the new pages.

[wbamberg]

Comparison operators now all have their own pages with interactive examples, and BCD is merged. Thanks for the reviews! I've also made https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Operators into a redirect and updated the links from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators.

I'm marking this one as complete as well.

[Elchi3]

Assignment operators now have their own pages with BCD merged.
I redirected to the main operator page and updated the links.
I also updated the links the guide page https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators#Assignment_operators

Half of the interactive examples are in place, missing is only the second part for the bitwise assignment operators: mdn/interactive-examples#1605 <-- this is now done as well. Marking assignment operators as complete.

[Elchi3]

For bitwise operators, the BCD is done and included in todays package.
The interactive-examples are filed in mdn/interactive-examples#1606.
I've created some pages today, the bitwise shift pages are still missing. Will try to get them done soon.

Two things came up that I'd like feedback on. This is on the current bitwise operator page:

• there is a section "Signed 32-bit integers" which should probably rather be a glossary that explains what 32 bit ints are? Where to move this to?
• The whole "Examples" section on that page I don't see fit anywhere. Anyone feels strongly about these? Move somewhere or delete? I think the examples are quite long and implement very specific things.

[Elchi3]

I decided to remove the sections I mentioned above. This work is now complete. The linter returns 0 errors.