JSDuck is formally unmaintained and seems abandonware by now. It is hurting our ability to properly document our code.
- Examples of problems:
- No support for @interface
- No support for namespaced events (change:title is invalid)
- No support for ES6 (T156469)
- Links that show it is unmaintained:
- Last beta was in 2013: https://github.com/senchalabs/jsduck/issues/633
- See the pulse graphs, barely any activity since end of 2013
- Formal announcement on readme
- Proposed alternatives:
- Use real JSDoc from npm
- Use documentationjs
Migration plan
- Research: Start researching who uses the JS HTML docs and what features are important to them, including:
- T353666 Attempt to query pageview data for JS HTML docs from the webrequest tables in Hive
- Put out a call for on-wiki feedback through relevant channels
- Scope improvements to the WMF theme: Informed by user feedback and documentation best practices, compile a list of critical usability fixes in the form of Phabricator tasks with clear descriptions and acceptance criteria. See T187672: Release jsdoc-wmf-theme 1.0 (Wikimedia theme for JSDoc3) and T138401#9079509.
- Consider temporary mitigations: To address concerns about the impact to documentation usability while work on the theme is in progress, we looked into options to help mitigate that impact in the short term. For MediaWiki core, we decided to use the MediaWiki version 1.41 JSDuck docs as a backup while the migration is in progress with the goal of completing the migration in time for version 1.42. In addition, after looking into a few other open-source theme options, we decided to move forward with the WMF theme.
Codebases to port to JSDoc
Only codebases that previously had a published doc.wikimedia.org JSDuck site are in scope. Once these are all converted, this ticket can be closed.
Please compare to the old JSDuck docs when converting these, to help with the conversion and to make sure nothing breaks or is missed.
| Done? | Repo | Ticket | Currently has JSDuck site on doc.wikimedia.org? (needs conversion) | Currently has JSDoc site on doc.wikimedia.org? (yay. all done) | Notes |
|---|---|---|---|---|---|
| ✅ | mediawiki/core | T352308 | JSDoc site | ||
| ✅ | mediawiki/extensions/CollaborationKit | T138401 | JSDoc site | ||
| ✅ | mediawiki/extensions/EventLogging | T357444 | JSDoc site | ||
| ✅ | mediawiki/extensions/Flow | JSDuck site | Skipping conversion due to Flow's imminent undeployment | ||
| mediawiki/extensions/GuidedTour | T367507 | JSDuck site | |||
| ✅ | mediawiki/extensions/Kartographer | T342864 | JSDoc site | ||
| ❓ | mediawiki/extensions/MobileFrontend | T188261 | JSDoc site | Not on jsdoc-wmf-theme yet due to 55 globals (fatal error) that need to be fixed | |
| ❓ | mediawiki/extensions/TemplateData | Gerrit | JSDoc site | Not on jsdoc-wmf-theme yet due to 5 globals (fatal error) that need to be fixed | |
| ✅ | mediawiki/extensions/VisualEditor (MediaWiki integration) | T250843 | JSDoc site | ||
| mediawiki/extensions/Wikibase | T342905 | JSDuck site | |||
| ✅ | mediawiki/skins/Minerva | Gerrit | JSDoc site | ||
| ✅ | oojs/core | Gerrit | JSDoc site | ||
| ✅ | oojs/ui (OOUI) | T185396 | JSDoc site | ||
| ❓ | oojs/router | T358813 | JSDuck site | JSDoc site (part of MediaWiki core) | Do the JSDuck config files in the repo need to be deleted? Does this need its tile taken off of doc.wikimedia.org now that it is in core? |
| ✅ | VisualEditor/VisualEditor (Standalone) | T250843 | JSDoc site |
Checklist for each migration
- Code documentation works fine, fix any problems
- Docs get properly published to docs.wikimedia.org e.g. https://doc.wikimedia.org/MobileFrontend/master/js/
- CI lints documentation properly with jenkins-bot on patches
- Documentation about how to run documentation in mw.org, README, etc is updated to point to the new instructions if any change
Migration guide
For how to set up JSDoc, see https://www.mediawiki.org/wiki/JSDoc.
JSDuck to JSDoc mapping
- Try to comply with:
- TypeScript supported JSDoc tags (other tags are simply ignored). This enables type checking for participating repos. Supported tags are:
- @type
- @param / @arg / @argument
- @returns / @return
- @typedef
- @callback
- @template
- @class / @constructor
- @this
- @extends / @augments
- @enum
- eslint-config-wikimedia style preferences. The linter improves the consistency of code across Wikimedia for participating repos.
- TypeScript supported JSDoc tags (other tags are simply ignored). This enables type checking for participating repos. Supported tags are:
- Type definitions themselves appear to be compatible as both JSDuck type definitions and JSDoc type definitions use Google Closure compiler type expressions. However, garbage in = garbage out.
- Many JSDuck types support optional descriptions on subsequent lines.
- Ironically, neither JSDoc nor JSDuck is as well documented as one would like.
| JSDuck tag | JSDoc tag and notes |
| @abstract | @abstract |
| @accessor | Unsupported. Only used by ExtJSBase. |
| @alias prefix.name | @alias aliasNamepath |
| @alternateClassName OtherClassName | What to do? @alias aliasNamepath? @typedef {type} namepath? Sparse usage. |
| @aside name | Unsupported. No usage. |
| @author Some name... | @author name <emailAddress> |
| @cfg, @cfg name, @cfg {Type} name, @cfg {Type} [name="default value"], @cfg {Type} name.subproperty | Use @param, or use`@typedef` for shared types |
| @chainable | Use @return {Type} where {Type} refers to the memberof class of the function instead. |
| @class, @class ClassName | @class name |
| @constructor | @return {type} description |
| @deprecated | @deprecated |
| @docauthor Some name... | Unsupported and unused. |
| @enum, @enum {Type}, @enum {Type} EnumName, @enum [EnumName=alias.*] | @enum {type} |
| @event, @event name | @event ~'className.eventName' (example: ~'util.addPortlet') |
| @evented | Unsupported. Only used by ExtJSBase. |
| @example | @example |
| @experimental, @experimental 2.0 Some description... | @experimental |
| @extends ParentClassName | @extends namepath |
| @fires eventName (in 5.x beta) | For hooks: @fires Hooks~'className.eventName' (example:Hooks~'util.addPortletLink') |
| @ftype name | Unsupported. No usage. |
| @hide | Unsupported. Only used by ExtJSBase. |
| @ignore | @ignore |
| @inheritable | What to do? Delete? |
| @inheritdoc, @inheritdoc ClassName, @inheritdoc #memberName, @inheritdoc ClassName#memberName, @inheritdoc ClassName#static-type-memberName | What to do? If no value, @inheritdoc. If value, @extends value? |
| @localdoc This documentation is only visible inside this class/member. (in 5.x beta) | What to do? Delete? |
| @markdown | Unsupported. No usage. |
| @member ClassName | What to do? @member {type} name, @memberof parentNamepath @memberof! parentNamepath, or something else? |
| @method, @method name | @method FunctionName |
| @mixins ClassName | @mixes OtherObjectPath |
| @new | Unsupported. No usage. |
| @override OverriddenClassName | @override |
| @param name, @param {Type} name, @param {Type} [name], @param {Type} [name="default-value"], @param {Type} name.subproperty | @param {type} name description. For an optional parameter: @param {type} [name] description or @param {type} [name=default value] description. See jsdoc.app. |
| @preventable | Unsupported. Only used by ExtJSBase. |
| @private | @private [{typeExpression}] |
| @property, @property name, @property {Type} name, @property {Type} [name="default value"], @property {Type} name.subproperty | @property {type} name description. For an optional property: @property {type} [name] description |
| @protected | @protected [{typeExpression}] |
| @ptype name | Unsupported. No usage. |
| @readonly | @readonly |
| @removed, @removed 2.0 Some description... | Unsupported. One usage in SemanticMediaWiki and otherwise only used by ExtJSBase. |
| @requires ClassName | @requires someModuleName |
| @return {Type}, @return {Type} return.subproperty (Multiple @return tags ) | Replace with single @return {Type} description and use @typedef {Object} Type to document the type. |
| @scss-mixin | Unsupported. No usage. |
| @since Ext JS 4.0 beta | @since versionDescription |
| @singleton | What to do? Custom tag? |
| @static | @static |
| @template | @template |
| @throws, @throws {Type} | @throws {type} free-form description |
| @type {Type}, @type Type | @type {type} free-form description |
| @uses ClassName | @see namepath or @see text. Mapping isn't one-to-one. |
| @var, @var $some-name, @var {Type} $some-name, @var {Type} [$some-name="default value"] | @member {type} name |
| @xtype | Unsupported. One usage in ExtTab and otherwise only uses by ExtJSBase. |
| {@link Class#member link text} | {@link namepathOrURL}, [link text]{@link namepathOrURL}, {@link namepathOrURL%7clink text}, {@link namepathOrURL link text (after the first space)} |
| {@img path/to/image.png alt text} | Usupported. Only used by ExtJSBase. |
| {@video vimeo 465123 Some description here...} | Unsupported. No usage. |