Prettify code blocks in JavaScript docs #9565

wbamberg · 2021-10-04T18:24:38Z

This is the result of running:

npx prettier --write ./files/en-us/web/javascript

...which has the effect of prettifying the JS code blocks in the JS documentation.

Just an experiment to see if we might want to do this.

wbamberg · 2021-10-04T19:07:19Z

files/en-us/web/javascript/guide/control_flow_and_error_handling/index.md

+  toString: function () {
+    return "I'm an object!";
+  },
+};


One thing is that it destroys nicely aligned comments, which is a bit sad.

wbamberg · 2021-10-04T19:12:41Z

files/en-us/web/javascript/reference/global_objects/array/slice/index.md

-slice(start, end)
+slice();
+slice(start);
+slice(start, end);


It also adds semicolons to Syntax section, which I'm not sure if we like. This section is odd though because although we are marking it up as JS, it isn't really.

We don't like - i.e. omission is deliberate decision.

Again if we want to run Prettier over JS, we should not mark up "syntax" as JS, because it isn't.

Slightly amusingly to me, I just tagged you on a discussion on prettier here: https://github.com/mdn/content/discussions/9901

If we adopt prettier as a "default" then I'd rather mark up as JS and include the semicolon. The syntax highlighting makes this more readable.

estelle · 2021-10-04T20:06:09Z

files/en-us/web/javascript/guide/working_with_objects/index.md

-  type: 'Invertebrates', // Default value of properties
-  displayType: function() {  // Method which will display type of Animal
+  type: "Invertebrates", // Default value of properties
+  displayType: function () {


spot checking, and this is the only 'concern' ... but it's ok here, though may not always be - to have the 'this comment explains this function' that was on the end of the line coming after the thing it explains instead of before it.

Also FWIW I much prefer function() { over function () {. If we did that there should be a fair bit of churn because it contradicts the style guide: https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript#use_expanded_syntax

estelle · 2021-10-04T20:07:33Z

files/en-us/web/javascript/guide/working_with_private_class_features/index.md

+total.increase(); // #count now = 8
+total.increase(5); // #count now = 13
+console.log(total.current); // expected output: 13
+total.reset(); // #count now = 7


the spacing of having all the output lined up was intentional and has been removed. Again, this is ok

estelle · 2021-10-04T20:14:48Z

files/en-us/web/javascript/reference/errors/missing_curly_after_property_list/index.md

@@ -1,12 +1,13 @@
 ---
-title: 'SyntaxError: missing } after property list'


All the 'don't do this' errors weren't corrected in this series. Not sure how the autoprefix missed it, but it's good it did.

never mind. found a case where it corrected a 'don't do this'

estelle · 2021-10-04T20:18:34Z

files/en-us/web/javascript/reference/errors/not_a_constructor/index.md

-function* f() {};
-var obj = new f;
+function* f() {}
+var obj = new f();


this should not have been changed.

If we want to run Prettier on code samples, I think we should handle this by using a different info string for "bad JS" code samples, so Prettier doesn't think it's JS.

Here's a link to a Prettier playground showing some options:

https://prettier.io/playground/#N4Igxg9gdgLgprEAuEAVAFgSwM4AIe7YQC2cuAsgIYBOA1gCYQDuUANLunADZcQA6UAQCpcuaHGGiYTflBG4Y6anAmCoAA00ArbAK5wYCrFADmAXgGLKMAZvUCBuADwBCALRvcAB2UwYmOGo3TBMoCGVcDwA+RzsdPQMjTFMLWCxsRjhsMOlw2ltNByhcON0oAHpy719-QODQ8NV9Q0Vk80t0mTpsWgAjAFcYXghabH6TLgBPAvs1Eu1sN17KegFK6oNaoJCw5QSW43a0nC7RmaKQVhAIL39obGRQGmpmAAUaBAeUSi4mSkmHldetRKGBaAYAMqUUgAGWScGQADMftg4ECQWDIV5QW1kDBqP00SA4MRenB6PRyTDKKZ+pQTHAAGLhYjWfymZAgSiDCCXEDoGDELgAdSw8Gw2LAcAhn0w-gAbnLJpywNhASBkqjqDBXiCTKykSiiToAB4Qtr6ACK-Qg8ENXFRV2x1C1nNZdEYLD5PmSMGFmHoimQAA4AAxOl6o4UgrycnxZQLyhFXACONvgupuXy5iygKkp9D5yjTmGUuvpBqQyIdRNRxEweIJtYtcGttoRVaNVxglF6-sD6GQACZuyDMFw2gBhEiV4nYACsfP6qNQva+1cdIHlhIAklBKbAIWBqJhbgBBfcQmCTfT21EAX3vQA

Can't it be trained to ignore js with the trailing example-bad - i.e. js example-bad is not treated as JS.

Can't it be trained to ignore js with the trailing example-bad - i.e. js example-bad is not treated as JS.

No. I think our only options would be to use the // prettier-ignore comment, or not to use js in the info string. I had hoped that we could use the  before the code block, but as you can see from the huge link above that doesn't work.

We could train the syntax highlighter to recognize bad-js as something to be highlighted (or even rewrite to as brush: js in the markdown-to-html conversion).

Or perhaps consider a more configurable alternative to prettier.

files/en-us/web/javascript/a_re-introduction_to_javascript/index.md

files/en-us/web/javascript/reference/global_objects/date/setutcminutes/index.md

hamishwillee · 2021-10-04T21:33:05Z

Honestly, lot of churn for little real value from what I'm seeing.

hamishwillee · 2021-10-18T22:26:56Z

I think we absolutely do want to do this, if we can configure it in a way we can all agree on - ideally aligned with other big projects. The starting point for those rules might be https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript#use_expanded_syntax

wbamberg · 2021-10-19T04:47:00Z

I think we absolutely do want to do this, if we can configure it in a way we can all agree on - ideally aligned with other big projects. The starting point for those rules might be https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript#use_expanded_syntax

Prettier, by design, doesn't give you many configuration options. The idea is that instead of spending time arguing about how you want things to be formatted, you just use Prettier: https://prettier.io/docs/en/why-prettier.html.

I'm very much in favour of this. Although, like everyone else, I have opinions about how code should be formatted, I'd much rather just adopt a consistent style, have tooling to make sure it gets applied, and never have to think about it again.

wbamberg · 2022-03-31T22:57:00Z

I'm closing this, because although we still definitely want to do it, I don't expect this PR to be merged in anything like this form.

Prettify code blocks in JavaScript docs

26b7a24

github-actions bot added the Content:JS JavaScript docs label Oct 4, 2021

wbamberg commented Oct 4, 2021

View reviewed changes

estelle reviewed Oct 4, 2021

View reviewed changes

hamishwillee reviewed Oct 4, 2021

View reviewed changes

files/en-us/web/javascript/a_re-introduction_to_javascript/index.md Show resolved Hide resolved

hamishwillee reviewed Oct 4, 2021

View reviewed changes

files/en-us/web/javascript/reference/global_objects/date/setutcminutes/index.md Show resolved Hide resolved

hamishwillee mentioned this pull request Oct 18, 2021

Fix typo "undeclated" #9903

Merged

wbamberg mentioned this pull request Dec 24, 2021

Replace deprecated onKeyPress with onKeyDown #8394

Merged

wbamberg closed this Mar 31, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Prettify code blocks in JavaScript docs #9565

Prettify code blocks in JavaScript docs #9565

wbamberg commented Oct 4, 2021

wbamberg Oct 4, 2021

wbamberg Oct 4, 2021

hamishwillee Oct 4, 2021

wbamberg Oct 18, 2021

hamishwillee Oct 18, 2021

estelle Oct 4, 2021 •

edited

Loading

hamishwillee Oct 18, 2021

estelle Oct 4, 2021

estelle Oct 4, 2021

estelle Oct 4, 2021

estelle Oct 4, 2021

wbamberg Oct 18, 2021

hamishwillee Oct 19, 2021

wbamberg Oct 19, 2021

hamishwillee Oct 22, 2021

hamishwillee commented Oct 4, 2021

hamishwillee commented Oct 18, 2021 •

edited

Loading

wbamberg commented Oct 19, 2021

wbamberg commented Mar 31, 2022

		@@ -1,12 +1,13 @@
		---
		title: 'SyntaxError: missing } after property list'

Prettify code blocks in JavaScript docs #9565

Prettify code blocks in JavaScript docs #9565

Conversation

wbamberg commented Oct 4, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

estelle Oct 4, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hamishwillee commented Oct 4, 2021

hamishwillee commented Oct 18, 2021 • edited Loading

wbamberg commented Oct 19, 2021

wbamberg commented Mar 31, 2022

estelle Oct 4, 2021 •

edited

Loading

hamishwillee commented Oct 18, 2021 •

edited

Loading