Below is a summary of the discussion from this week’s JavaScript 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 (agenda, Slack 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 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 PHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher 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 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 Gutenberg 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