Documenting JavaScript in Core

We had a lively session on JavaScript in WordPress core 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 code that power the 3.5+ media experience. The JS 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 DocBlock on every JavaScript function. Consider this your battle cry.

Supplemental Documentation

Aside from inline docs, 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!