The JSDoc theme creates beautiful documentation but also attempts to validate that every reference is documented. This does not work well for repositories that use many foreign types. E.g., DOM types such as HTMLElement, HTMLInputElement, Event, etc, or externally resolved types such as void. I think it would be more practical to have a sensible default for external types or to lower checks to a warning. If that doesn't work, maybe allowing link checking to be skipped as an environment argument or passing a list of foreign types would work better.
Adding @external to every foreign type of every signature does not seem to scale well:
/** * Dismiss the target when clicking or focusing elsewhere and update the `aria-expanded` attribute * based on checkbox state (target visibility) changes made by **the user.** When tapping the button * itself, clear the focus outline. * * This function calls the other bind* functions and is the only expected interaction for most use * cases. It's constituents are provided distinctly for the other use cases. * * @param {Window} window * @param {HTMLInputElement} checkbox The underlying hidden checkbox that controls target * visibility. * @param {HTMLElement} button The visible label icon associated with the checkbox. This button * toggles the state of the underlying checkbox. * @param {Node} target The Node to toggle visibility of based on checkbox state. * @return {void} * * @external Window * @external HTMLInputElement * @external HTMLElement * @external Node * @external void */
This might not seem like a big deal for one function but is a lot of extra boilerplate on top of the already verbose JSDoc syntax when considered across hundreds of functions. In my view, the current behavior greatly discourages good documentation or documentation at all.
Edit: this is at least partly resolvable via configuration. E.g.:
{ ... "wmf": { "linkMap": { "MW": "https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw", "JQueryStatic": "https://api.jquery.com", "Document": "https://developer.mozilla.org/docs/Web/API/Document", "Window": "https://developer.mozilla.org/docs/Web/API/Window", "void": "#" } } } }
^Update the docs and close this task if nothing else is needed. Question though: can a bunch of these appear in jsdoc-wmf-theme itself or a plugin? Adding the more common ones like HTMLInputElement, Window, void, etc to every repo doesn't scale well for all of MediaWiki (e.g., see these JSDuck configs).