From: Timo Tijhof Date: Mon, 10 Jun 2013 04:40:21 +0000 (+0200) Subject: mediawiki.js: Clean up and improve documentation coverage X-Git-Tag: 1.31.0-rc.0~19379 X-Git-Url: https://git.cyclocoop.org/%242?a=commitdiff_plain;h=a0c6d38d225c3bcf0e23563fb88683376d44e97f;p=lhc%2Fweb%2Fwiklou.git mediawiki.js: Clean up and improve documentation coverage Function addStyleTag was only documented as a private function, since a while now it is also exposed as a public method. Rename the private function so that they can both be included in the JSDuck index (jsduck can't deal with name clashes between public and private). Optimised by letting it inherit the documentation instead of repeating it. The following were missing documentation: * mw * mw.hook * mw.legacy * mw.loader#addEmbeddedCSS Moved assignment of `done` in mw.loader#addScript to where it was needed. The other if/else paths in that function don't use it and don't need it to have a value. With the introduction of mw.log#deprecate (fe46903) we no longer need mw.legacy. mw.legacy was created for future use to move legacy stuff into to make it easier to keep track of where they are used (simple search for 'mw.legacy') however that never happened and in retrospect was probably a bad idea as it would require people to change code twice. We now have a much cleaner solution now that we're able to create little accessors on any host-object with mw.log#deprecate. This makes mw.legacy obsolete and it should not be used for anything. Just in case something is using it I won't remove it just yet, instead I've deprecated the (what would have become the) deprecator ;-). We should be able to remove this in 1.23. Note: Can't use mw.log#deprecate here because that isn't defined yet at this point, this is the core library which can't have any dependencies. Change-Id: I5d241e4284f07a6be271c04cec3a5833dbaeed91 --- diff --git a/resources/mediawiki/mediawiki.js b/resources/mediawiki/mediawiki.js index d1991320c7..883a63f5dc 100644 --- a/resources/mediawiki/mediawiki.js +++ b/resources/mediawiki/mediawiki.js @@ -259,6 +259,8 @@ var mw = ( function ( $, undefined ) { }; /** + * Base library for MediaWiki. + * * @class mw * @alternateClassName mediaWiki * @singleton @@ -302,6 +304,14 @@ var mw = ( function ( $, undefined ) { libs: {}, /** + * Access container for deprecated functionality that can be moved from + * from their legacy location and attached to this object (e.g. a global + * function that is deprecated and as stop-gap can be exposed through here). + * + * This was reserved for future use but never ended up being used. + * + * @deprecated since 1.22: Let deprecated identifiers keep their original name + * and use mw.log#deprecate to create an access container for tracking. * @property */ legacy: {}, @@ -424,11 +434,11 @@ var mw = ( function ( $, undefined ) { * * @private * @param {string} text CSS text - * @param {Mixed} [nextnode] An Element or jQuery object for an element where - * the style tag should be inserted before. Otherwise appended to the ``. - * @return {HTMLElement} Node reference to the created `