Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

In JS docs, use Note: consistently at the start of notes #4504

Merged
merged 5 commits into from
Apr 27, 2021
Merged

In JS docs, use Note: consistently at the start of notes #4504

merged 5 commits into from
Apr 27, 2021

Conversation

wbamberg
Copy link
Collaborator

This PR was inspired by this subthread: #4352 (comment) and it edits the JS docs to try to use "Note:" consistently at the start of notes. This should make it easier for a Markdown conversion process to convert these things.

@wbamberg wbamberg requested a review from a team as a code owner April 26, 2021 23:37
@wbamberg wbamberg requested review from Rumyra and removed request for a team April 26, 2021 23:37
@wbamberg wbamberg mentioned this pull request Apr 26, 2021
Merged
@github-actions
Copy link
Contributor

github-actions bot commented Apr 26, 2021 •
edited
Loading

Preview URLs

Flaws

Note! 37 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/JavaScript/Data_structures
Title: JavaScript data types and data structures
on GitHub
Flaw count: 1

  • broken_links:
    • Can't resolve /en-US/docs/Storage

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll
Title: String.prototype.replaceAll()
on GitHub
Flaw count: 2

  • broken_links:
    • Anchor not lowercase
    • Anchor not lowercase

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
Title: Error
on GitHub
Flaw count: 5

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/eval redirects to /en-US/docs/Web/JavaScript/Reference/Global_Objects/eval
    • /en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/captureStackTrace does not exist
    • /en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/description does not exist
    • /en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/number does not exist
  • broken_links:
    • Can't resolve /en-US/docs/Web/JavaScript/Guide/Statements#Exception_handling_statements

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy/Proxy/set
Title: handler.set()
on GitHub
Flaw count: 2

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy/handler redirects to /en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy/Proxy
  • bad_bcd_links:
    • no explanation!

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Reduce
Title: Array.prototype.reduce()
on GitHub
Flaw count: 1

  • macros:
    • /en-US/docs/Web/API/Object/defineProperty does not exist

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from
Title: Array.from()
on GitHub
Flaw count: 1

  • broken_links:
    • Can't resolve /en-US/docs/Web/JavaScript/Guide/iterable

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach
Title: Array.prototype.forEach()
on GitHub
Flaw count: 2

  • broken_links:
    • Anchor not lowercase
    • No need for the pathname in anchor links if it's the same page

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined
Title: undefined
on GitHub
Flaw count: 2

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Reserved_Words redirects to /en-US/docs/Web/JavaScript/Reference/Lexical_grammar#keywords
    • /en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Operators redirects to /en-US/docs/Web/JavaScript/Reference/Operators

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf
Title: Object.prototype.valueOf()
on GitHub
Flaw count: 1

  • broken_links:
    • Can't resolve /en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators#Unary_plus

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
Title: Date
on GitHub
Flaw count: 1

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleFormat does not exist

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then
Title: Promise.prototype.then()
on GitHub
Flaw count: 2

  • broken_links:
    • Anchor not lowercase
    • Can't resolve /en-US/docs/Web/API/GlobalFetch/fetch

URL: /en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields
Title: Public class fields
on GitHub
Flaw count: 1

  • bad_bcd_links:
    • no explanation!

URL: /en-US/docs/Web/JavaScript/Reference/Errors/Too_much_recursion
Title: InternalError: too much recursion
on GitHub
Flaw count: 1

  • broken_links:
    • Anchor not lowercase

URL: /en-US/docs/Web/JavaScript/Reference/Statements/return
Title: return
on GitHub
Flaw count: 2

  • broken_links:
    • Anchor not lowercase
    • Can't resolve /en-US/docs/Web/JavaScript/Reference/Functions_and_function_scope

URL: /en-US/docs/Web/JavaScript/Reference/Statements/with
Title: with
on GitHub
Flaw count: 4

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/prototype does not exist
    • /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/prototype does not exist
  • broken_links:
    • Can't resolve /en-US/docs/Web/JavaScript/Reference/Functions_and_function_scope/Strict_mode
    • Can't resolve /en-US/docs/Web/JavaScript/Reference/Functions_and_function_scope/Strict_mode

URL: /en-US/docs/Web/JavaScript/Reference/Statements/let
Title: let
on GitHub
Flaw count: 1

  • broken_links:
    • Anchor not lowercase

URL: /en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment
Title: Destructuring assignment
on GitHub
Flaw count: 2

  • broken_links:
    • Anchor not lowercase
    • Can't resolve /en-US/docs/Web/JavaScript/Reference/Operators/Assignment_Operators

URL: /en-US/docs/Web/JavaScript/Reference/Operators/this
Title: this
on GitHub
Flaw count: 1

  • broken_links:
    • Can't resolve /en-US/docs/Web/Guide/Events/Event_handlers

URL: /en-US/docs/Web/JavaScript/Reference/Strict_mode
Title: Strict mode
on GitHub
Flaw count: 4

  • broken_links:
    • Can't resolve https://developer.mozilla.org/docs/Glossary/Sloppy_mode
    • Can't resolve https://developer.mozilla.org/docs/Glossary/Sloppy_mode
    • Can't resolve /en-US/docs/Web/API/WindowTimers/setTimeout
    • Can't resolve /en-US/docs/Glossary/primitive

URL: /en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions
Title: Arrow function expressions
on GitHub
Flaw count: 2

  • broken_links:
    • Can't resolve /en-US/docs/Glossary/constructor
    • Can't resolve /en-US/docs/Web/JavaScript/Reference/Functions/Rest_parameters

URL: /en-US/docs/Web/JavaScript/Reference/Functions/get
Title: getter
on GitHub
Flaw count: 3

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineGetter redirects to /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/__defineGetter__
    • /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineSetter redirects to /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/__defineSetter__
  • broken_links:
    • Anchor not lowercase

URL: /en-US/docs/Web/JavaScript/Guide/Grammar_and_types
Title: Grammar and types
on GitHub
Flaw count: 1

  • broken_links:
    • No need for the pathname in anchor links if it's the same page

URL: /en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Assertions
Title: Assertions
on GitHub
Flaw count: 1

  • broken_links:
    • Link points to the page it's already on

URL: /en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Cheatsheet
Title: Regular expression syntax cheatsheet
on GitHub
Flaw count: 5

  • heading_links:
    • h2 heading contains an <a> tag
    • h2 heading contains an <a> tag
    • h2 heading contains an <a> tag
    • h2 heading contains an <a> tag
    • h2 heading contains an <a> tag

External URLs

URL: /en-US/docs/Web/JavaScript/Closures
Title: Closures
on GitHub

URL: /en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain
Title: Inheritance and the prototype chain
on GitHub

URL: /en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript
Title: A re-introduction to JavaScript (JS tutorial)
on GitHub

URL: /en-US/docs/Web/JavaScript/Data_structures
Title: JavaScript data types and data structures
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random
Title: Math.random()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/values
Title: TypedArray.prototype.values()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat
Title: Intl.DateTimeFormat() constructor
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator
Title: Intl.Collator() constructor
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp
Title: RegExp
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/String
Title: String
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/String/big
Title: String.prototype.big()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fontsize
Title: String.prototype.fontsize()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fontcolor
Title: String.prototype.fontcolor()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll
Title: String.prototype.replaceAll()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
Title: Error
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy/Proxy/set
Title: handler.set()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
Title: Map
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort
Title: Array.prototype.sort()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/values
Title: Array.prototype.values()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Reduce
Title: Array.prototype.reduce()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some
Title: Array.prototype.some()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from
Title: Array.from()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every
Title: Array.prototype.every()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex
Title: Array.prototype.findIndex()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach
Title: Array.prototype.forEach()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined
Title: undefined
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/call
Title: Function.prototype.call()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name
Title: Function.name
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/defineProperty
Title: Reflect.defineProperty()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/Planned_changes
Title: Planned changes to shared memory
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/SharedArrayBuffer
Title: SharedArrayBuffer() constructor
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf
Title: Object.prototype.valueOf()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor
Title: Object.prototype.constructor
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/isPrototypeOf
Title: Object.prototype.isPrototypeOf()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
Title: Date
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse
Title: Date.parse()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
Title: Promise
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then
Title: Promise.prototype.then()
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields
Title: Public class fields
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Errors/Too_much_recursion
Title: InternalError: too much recursion
on GitHub

No external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Statements/return
Title: return
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Statements/async_function
Title: async function
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Statements/with
Title: with
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Statements/let
Title: let
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
Title: for await...of
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment
Title: Destructuring assignment
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Operators/this
Title: this
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Operators/new
Title: new operator
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Strict_mode
Title: Strict mode
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Functions/arguments/length
Title: arguments.length
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions
Title: Arrow function expressions
on GitHub

URL: /en-US/docs/Web/JavaScript/Reference/Functions/get
Title: getter
on GitHub

URL: /en-US/docs/Web/JavaScript/Guide/Grammar_and_types
Title: Grammar and types
on GitHub

URL: /en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling
Title: Control flow and error handling
on GitHub

No external URLs

URL: /en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Groups_and_Ranges
Title: Groups and ranges
on GitHub

URL: /en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Assertions
Title: Assertions
on GitHub

URL: /en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Character_Classes
Title: Character classes
on GitHub

URL: /en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Cheatsheet
Title: Regular expression syntax cheatsheet
on GitHub

URL: /en-US/docs/Web/JavaScript/Guide/Keyed_collections
Title: Keyed collections
on GitHub

URL: /en-US/docs/Web/JavaScript/Guide/Details_of_the_Object_Model
Title: Details of the object model
on GitHub

URL: /en-US/docs/Web/JavaScript/Guide/Functions
Title: Functions
on GitHub

(this comment was updated 2021-04-27 02:26:42.851288)

(this comment was updated 2021-04-27 02:38:45.130264)

(this comment was updated 2021-04-27 02:47:08.350446)

(this comment was updated 2021-04-27 17:16:47.903861)

@hamishwillee
Copy link
Collaborator

hamishwillee commented Apr 27, 2021 •
edited
Loading

@wbamberg
I guess it doesn't matter, but the "official" approach is IMO better. That is to make the notes like this:

<div class="notecard note">
   <h4>Note</h4>
   <p>blah blah</p>
</div>

Why?

  • it is the documented way to do notes in the guide
  • notecard is the proper class for an aside. A warning is "notecard warning".
  • very easy for a parser to pull out the heading and compare it to the intent.

PS I've been moving most things I work on to this for some months.

@wbamberg
Copy link
Collaborator Author

FWIW I really don't like using headings for this. I think headings make promises about page structure and hierarchy, and I don't think notes should participate in page structure.

But, that's kind of irrelevant because they're going away anyway. The purpose of this PR is to make our JS notes more consistent, so a conversion process can handle them without a hundred special cases.

There are 231 instances of div.note in the JS docs. Of these, the first child node is as follows:

  • STRONG: 10
  • P: 215
  • H4: 2
  • H2: 1

So if I changed them all to use H2-H6 I'd have to rewrite almost every note.

Of the 215 P instances, every one has a STRONG first child, and after this PR almost all of those contain "Note:" as the text content. So it would be better to update the 13 other instances, and to make sure all the text contents are consistently "Note:".

@hamishwillee
Copy link
Collaborator

Sure. If you're just talking about JS and the timeline for conversion is relatively short 100% agree.

@wbamberg
Copy link
Collaborator Author

I just pushed a couple more changes, and I think now, all the div.note instances in JS are now like:

<div class="note" (and sometimes "notecard" too)
  <p><strong>Note:</strong> Yadda yadda</p>
...
</div>

Elchi3
Elchi3 approved these changes Apr 27, 2021
View reviewed changes
Copy link
Member

@Elchi3 Elchi3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Just one question if it is warning or note

files/en-us/web/javascript/reference/global_objects/typedarray/values/index.html Outdated
@@ -56,7 +56,7 @@ <h3 id="Iteration_using_.next">Iteration using .next()</h3>
iteraror.next().value; // undefined </pre>

<div class="notecard warning">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note or warning?

Suggested change
<div class="notecard warning">
<div class="notecard note">

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh this is my mistake. That was a warning so I should not have touched it.

@Elchi3 Elchi3 merged commit 29b2bfb into mdn:main Apr 27, 2021
@wbamberg wbamberg mentioned this pull request Apr 30, 2021
Merged
@wbamberg wbamberg mentioned this pull request Jun 10, 2021
Closed
13 tasks
@wbamberg wbamberg mentioned this pull request Aug 3, 2021
Closed
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 14, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@Elchi3 Elchi3 Elchi3 approved these changes

@Rumyra Rumyra Awaiting requested review from Rumyra

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@wbamberg @hamishwillee @Elchi3