JavaScript Chat Summary: March 17, 2020

Below is a summary of the discussion from this week’s JavaScript 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 tag 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 PHP 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 JS documentation standards, assuming there is no opposition presented in the coming days.
  • Disable the JSDoc since format validation for 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