JavaScript Chat Summary: March 17, 2020

Below is a summary of the discussion from this week’s JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. chat (agendaSlack transcript).

Have a topic for discussion for the next meeting? Leave a suggested edit on next week’s agenda.

Agenda Items

JSDoc Documentation Standards

(Slack conversation)

Question: Does it make sense to document changes to a function over time, and if so, how?

Context: https://github.com/WordPress/gutenberg/pull/20427#discussion_r386396607

The current JavaScript documentation standards restrict the @since tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) to include only the version number:

@since x.x.x: Should always be 3-digit (e.g. @since 3.6.0).

This is in contrast to the PHP documentation standards, which include guidelines around using @since as a changelog:

If significant changes have been made to a function, hook, class, or method, additional @since tags, versions, and descriptions should be added to provide a changelog for that function.

Proposal: Incorporate some adaptation of the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 since changelog guidelines into the JavaScript inline documentation standards.

Discussion Points:

  • @nerrad asks if this could be used to pull documentation automatically from the source code. This is quite possible, and is likely exactly what is done with the PHP source code documentation (example documentation and source).

Action Items:

  • Update the JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. documentation standards, assuming there is no opposition presented in the coming days.
  • Disable the JSDoc since format validation for GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ in the related changelog (already done)

News Roundup

This roundup contains a few links for Gutenberg and JavaScript related news curated (and commented on) by @nerrad

Other Random Stuff:

#core-js, #javascript