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 (!).
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.
We will discuss JSDoc in the weekly Inline Docs meeting in the #docs channel on November 12, 2014 20:00. Join us!