Update to 1.41, fix types & cleanup docs

[Derugon]

This merge request contains various type and documentation changes, mostly to add MediaWiki 1.41 declarations and to fix various JSdoc inconsistencies and type issues.

Below is a (non exhaustive) list of proposed changes:

JSDoc changes

• Update comments to 1.41:
  • add missing comments to $.client, $.textSelection, mw.html, mw.loader.store.stats, mw.message, mw.notification, mw.storage.session, mw.Uri, and mw.widgets.
  • update comments of mw.Api and mw.util.isTemporaryUser.
  • scrap mw.config comments, along with property types.
• Synchronize JSDoc types with TypeScript types.
• Add missing @link (instead of @see, for referencing other members), @see, and @since annotations.
• Unify annotation conventions:
  • use ``` code blocks, and specify language name as much as possible.
  • replace @return with @returns.
  • replace *, Mixed with any.
  • replace {T?} x with {T} [x] to match expected behavior.
• Move @property and @param annotations to inner objects when sub-property referencing is used.
• Remove redundant annotations:
  • @class, @constructor, @extends, @fires, @member, @method, @property, @returns {void}, @singleton, and @static.
  • @private and @protected where corresponding TS keywords can be used.
  • @chainable where this can be used.

Type changes

• Add missing declarations from 1.41:
  • update api_params.d.ts generated list from Wikipedia API (1.42.0-wmf.18).
  • add global mediaWiki.
  • add libs, log, and trackQueue to mw.
  • add missing mw.config properties.
  • add mw.errorLogger.
  • add OOJS static properties to mw.ForeignApi and mw.ForeignRest.
  • make mw.language.months a namespace and specify properties.
  • add impl to mw.loader and missing mw.loader.moduleRegistry properties.
  • add makeDeprecated to mw.log.
  • add isParseable to mw.Message.
  • add acquireTempUserName and clientPrefs to mw.user.
  • add addPortlet and getArrayParam to mw.util.
• Use more shared interfaces for similar or complex types.
• Stricten some types:
  • replace any values of $.client.test, $.colorUtil.getColorBrightness, mw.cookie.set, mw.language.data, mw.language.getDigitTransformTable, mw.language.getSeparatorTransformTable, mw.language.setData, mw.loader.implement, mw.loader.require, mw.loader.store.items, mw.storage.clearExpired, mw.storage.getExpiryKeys, mw.Title.getUrl, mw.track, mw.trackError, mw.Uri.query, and mw.Uri.extend.
  • specify callback arguments of addOnloadHook, mw.loader.addScriptTag, mw.loader.enqueue, mw.loader.using, mw.trackSubscribe, mw.trackUnsubscribe, and mw.UriRelative.
  • specify query parameters and promise results of various mw.Api methods.
  • use fixed-size arrays with $.colorUtil color arrays.
  • infer argument type from boolean result with mw.util.isIPv4Address and mw.util.isIPv4Address.
  • use false literal instead of boolean with return type of mw.loader.store.get, mw.storage.get, and mw.user.getRegistration.
  • use string enumeration with type argument of mw.loader.load and module state argument of mw.loader.state.
  • use template strings with return type of mw.ForeignApi.getOrigin and mw.Uri.toString.
• Improve type inference based on function arguments:
  • add type variables to $.colorUtil.getRGB, mw.language.gender, mw.language.preConvertPlural, and mw.log.deprecate.
  • add alternative declarations to mw.language.convertNumber and mw.language.gender.
• Add optional type variables to help manually improving type checking when desired:
  • to specify loaded modules of mw.loader.resolve.
  • to specify allowed keys of mw.Map.exists and mw.Map.set.
• Add autocompletion to common parameter values:
  • base and legacy token types of mw.Api.badToken, mw.Api.getToken, and mw.Api.postWithToken methods.
  • known properties of mw.Map methods, by using another ExtensibleMap interface (see wg variables are not autocompleted #37).

Specific type fixes

• Fix some functions not specifying some "error" return values:
  • null for mw.cookie.get, mw.language.gender, mw.notification.defaults.type, mw.Title.newFromFileName, mw.Title.newFromImg, and mw.Title.newFromUserInput.
  • false for mw.cookie.getCrossSite, mw.notification.defaults.classes and mw.notification.defaults.id.
• Add missing command options argument to $.textSelection() when called with setContents and replaceSelection.
• Fix $.textSelection("getCaretPosition", { startAndEnd: x }) not allowing x: boolean.
• Prevent calling $.textSelection("setSelection") without any options, as start is required.
• Add a default definition of $.textSelection for custom commands, registered via $.textSelection("register").
• Add missing prefix to properties of some api_params.d.ts interfaces.
• Fix importStylesheet and importStylesheetURI eventually returning null, which actually never appens.
• Fix defaults of mw.Api, mw.ForeignApi, mw.ForeignRest, and mw.Rest having all properties optional. Some are optional, but some are always defined.
• Fix mw.Api.assertCurrentUser return type, this function extends the given query parameters, but does not do any actual API request.
• Fix mw.Api.chunkedUploadToStash not allowing an input HTML element as argument.
• Fix mw.Api.getMessages and mw.Api.loadMessages not allowing to query a single string message.
• Fix mw.Api.loadMessagesIfMissing returning an API result: the actual query result is consumed by the function, only the boolean mw.Map.set result is returned.
• Fix wgCaseSensitiveNamespaces property of mw.config being a list of strings instead of integers.
• Add missing sameSiteLegacy property to options of mw.cookie.set.
• Rename mw.experiment to mw.experiments.
• Fix mw.ForeignRest allowing a URI object as argument. However, mw.ForeignRest does not check for URI objects, while mw.ForeignApi does.
• Fix mw.format mistakenly allowing anything as parameter replacement.
• Fix mw.html.element not allowing attributes to have boolean or number values.
• Fix mw.language.convertPlural asking for string instead of integers, when specifying plural forms.
• Remove commafyNumber, flipTransform, and pad from mw.language. These declarations are mistakenly included in the API documentation (supposedly missing an @ignore annotation).
• Fix mw.loader.register signature when given multiple modules: all properties should be given multiple times, not only the module name.
• Fix mw.Map.values optional keys being required with null instead of being optional (and update html scrapper accordingly).
• Infer mw.Map.get return type from both selection type and fallback type.
• Add missing format parameter to mw.Message.parser and mw.Message.toString.
• Fix mw.notify and mw.notification.notify not allowing mw.Message objects as argument.
• Add missing options parameter to mw.requestIdleCallback.
• Add missing return type to mw.storage.setExpires.
• Fix mw.Title.exists not allowing a title string as argument.
• Fix mw.Title.newFromUserInput not allowing an empty object as options.
• Fix mw.UriRelative returning a mw.Uri instance instead of a new constructor. This is also wrongly typed in the MediaWiki source code.
• Fix mw.Uri constructor not allowing a boolean as options. This is marked as backward-compatibility in JSDoc, and is still handled in the source code.
• Fix mw.user.getGroups and mw.user.getRights not chaining the promise result correctly when given a callback argument.
• Fix mw.util.debounce and mw.util.throttle not indicating that the function's return type will be discarded.
• Fix mw.util.getUrl not allowing parameters to have boolean or number values, while these are explicitely stringified in the function.

Other changes

• Remove redundant namespace prefixes.
• Remove unused imports.
• Remove api_params.d.ts linter exception, so issues (other than no-empty-interface) can still be detected.

[AnYiEE]

If you're willing, you can add the definition mentioned here. #32

[Derugon]

If you're willing, you can add the definition mentioned here. #32

mw.deflate does not seem to usually be loaded on page load on various wikis. Personally, I'm not in favour of having the mw namespace filled with all existing modules every time I include this package. (here was a proposal on this matter: #35). I would like to keep addition of other modules for another pull request.

[AnYiEE]

mw.deflate does not seem to usually be loaded on page load on various wikis.

Yes, it usually always loads after opening VisualEditor.

[Derugon]

mw.user is missing clientPrefs singleton, check it at AnYiEE@f96695c

Done, thank you.
(note: difference with commit is the clientPrefs.set return type, the function never returns true)

[Derugon]

I've more or less finished re-reading all source code files, so I'm done with the changes of this PR.
I'm sorry about the commits mess, this PR became much bigger than it was originally supposed to be, I can split this PR into multiple smaller ones if preferred.

[siddharthvp]

Thanks a lot for the stellar work here. This looks thorough and meticulous. Thanks to @AnYiEE for reviewing it as well. Due to the size of the PR and time constraints, I am unable to go through it all so I'm just merging it as is. We can iterate over any improvements.