Documenting JavaScript in Core

We had a lively session on 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. in WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. at the Community Summit last week. Topics were varied, but I’d like to sum up a few threads that point towards an actionable goal: better documentation in JavaScript.

New Feature JavaScript is complex

WordPress’ internal JavaScript “libraries” are hard to understand, if not impenetrable for many core developers. For example, the 8000+ lines of codeLines of Code Lines of code. This is sometimes used as a poor metric for developer productivity, but can also have other uses. that power the 3.5+ media experience. The JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. here hasn’t been written for other developers to consume, so architectural decisions end up being expressed only in code, often without documentation.

As feature development has become much more JavaScript-driven, we should do whatever we can to make our code comprehensible for fellow core developers. Comprehensible code takes many shapes, but one that everyone can agree on is documentation. Up until now, JavaScript documentation has been an afterthought. We need to make an about-face in this respect.

Adopting JSDoc

Core is adopting the JSDoc standard. Last year, WordPress standardized PHP inline documentation. Inline documentation surfaces relevant information to developers about code. This is very helpful (necessary?) when you’re wondering what arguments are to be passed into a class constructor that’s seven levels deep in inheritance (!).

Picking a documentation standard also makes parsing code possible, to extract this structured data. Our bespoke PHP parser feeds inline documentation into the new WP code reference. Choosing a JS documentation standard makes an auto-generated Javascript code reference a possibility later down the line.

@kpdesign, @adamsilverstein, @drewapicture and I have been drafting a page on JavaScript Inline Documentation Standards, which will land in the core contributor handbook very soon.

Let us rally around JS documentation, and get a DocBlockdocblock (phpdoc, xref, inline docs) on every JavaScript function. Consider this your battle cry.

Supplemental Documentation

Aside from inline docsinline docs (phpdoc, docblock, xref), we need a place for high-level architectural explanation of our JavaScript to live, probably in the core contributor handbook.  Many at the summit noted that with a few key insights, internal libraries are much easier grokked. @gcorne and I started on documentation for media. We’ll see how this goes.

Also, insightful tidbits which would have no place in inline documentation could be answered here, to answer questions like why and when we provide no-js fallbacks.

Follow-up Meeting

We will discuss JSDoc in the weekly Inline Docs meeting in the #docs channel on November 12, 2014 20:00. Join us!