Krinkle has uploaded a new change for review.
https://gerrit.wikimedia.org/r/67648
Change subject: mediawiki.js: Clean up and improve documentation coverage
......................................................................
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
---
M resources/mediawiki/mediawiki.js
1 file changed, 49 insertions(+), 24 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/core
refs/changes/48/67648/1
diff --git a/resources/mediawiki/mediawiki.js b/resources/mediawiki/mediawiki.js
index d199132..0ca141b 100644
--- a/resources/mediawiki/mediawiki.js
+++ b/resources/mediawiki/mediawiki.js
@@ -259,6 +259,8 @@
};
/**
+ * Base library for MediaWiki.
+ *
* @class mw
* @alternateClassName mediaWiki
* @singleton
@@ -302,6 +304,14 @@
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 @@
*
* @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 `<head>`.
- * @return {HTMLElement} Node reference to the created
`<style>` tag.
+ * @param {HTMLElement|jQuery} [nextnode=document.head]
The element where the style tag should be
+ * inserted before. Otherwise it will be appended to
`<head>`.
+ * @return {HTMLElement} Reference to the created
`<style>` element.
*/
- function addStyleTag( text, nextnode ) {
+ function newStyleTag( text, nextnode ) {
var s = document.createElement( 'style' );
// Insert into document before setting cssText
(bug 33305)
if ( nextnode ) {
@@ -474,8 +484,13 @@
}
/**
+ * Add a bit of CSS text to the current browser page.
+ *
+ * Will be appended to an existing
ResourceLoader-created `<style>` tag or create
+ * a new one based on whether the given `cssText` is
safe for extension.
+ *
* @param {string} [cssText=cssBuffer] If called
without cssText,
- * the internal buffer will be inserted instead.
+ * the internal buffer will be inserted instead.
* @param {Function} [callback]
*/
function addEmbeddedCSS( cssText, callback ) {
@@ -547,7 +562,7 @@
}
}
- $( addStyleTag( cssText, getMarker() ) ).data(
'ResourceLoaderDynamicStyleTag', true );
+ $( newStyleTag( cssText, getMarker() ) ).data(
'ResourceLoaderDynamicStyleTag', true );
cssCallbacks.fire().empty();
}
@@ -820,8 +835,7 @@
*/
function addScript( src, callback, async ) {
/*jshint evil:true */
- var script, head,
- done = false;
+ var script, head, done;
// Using isReady directly instead of storing it
locally from
// a $.fn.ready callback (bug 31895).
@@ -833,6 +847,7 @@
// IE-safe way of getting the <head>.
document.head isn't supported
// in old IE, and doesn't work when in
the <head>.
+ done = false;
head = document.getElementsByTagName(
'head' )[0] || document.body;
script = document.createElement(
'script' );
@@ -852,12 +867,12 @@
// Handle
memory leak in IE
script.onload =
script.onreadystatechange = null;
- // Remove the
script
+ // Detach the
element from the document
if (
script.parentNode ) {
script.parentNode.removeChild( script );
}
- // Dereference
the script
+ // Dereference
the element from javascript
script =
undefined;
callback();
@@ -1150,10 +1165,15 @@
/* Public Methods */
return {
- addStyleTag: addStyleTag,
+ /**
+ * @inheritdoc #newStyleTag
+ * @method
+ */
+ addStyleTag: newStyleTag,
/**
- * Requests dependencies from server, loading
and executing when things when ready.
+ * Batch-request queued dependencies from the
server. This will load and execute
+ * when things when ready.
*/
work: function () {
var reqBase, splits,
maxQueryLength, q, b, bSource, bGroup, bSourceGroup,
@@ -1315,7 +1335,7 @@
},
/**
- * Registers a module, letting the system know
about it and its
+ * Register a module, letting the system know
about it and its
* properties. Startup modules contain calls to
this function.
*
* @param {string} module Module name
@@ -1366,9 +1386,10 @@
},
/**
- * Implements a module, giving the system a
course of action to take
- * upon loading. Results of a request for one
or more modules contain
- * calls to this function.
+ * Implement a module given the components that
make up the module.
+ *
+ * When #load or #using requests one or more
modules, the server
+ * response contain calls to this function.
*
* All arguments are required.
*
@@ -1423,7 +1444,7 @@
},
/**
- * Executes a function as soon as one or more
required modules are ready
+ * Execute a function as soon as one or more
required modules are ready.
*
* @param {string|Array} dependencies Module
name or array of modules names the callback
* dependends on to be ready before executing
@@ -1460,7 +1481,7 @@
},
/**
- * Loads an external script or one or more
modules for future use
+ * Load an external script or one or more
modules for future use.
*
* @param {string|Array} modules Either the
name of a module, array of modules,
* or a URL of an external script or style
@@ -1540,7 +1561,7 @@
},
/**
- * Changes the state of a module
+ * Change the state of a module.
*
* @param {string|Object} module module name or
object of module name/state pairs
* @param {string} state state name
@@ -1569,9 +1590,9 @@
},
/**
- * Gets the version of a module
+ * Get the version of a module.
*
- * @param {string} module name of module to get
version for
+ * @param {string} module Name of module to get
version for
*/
getVersion: function ( module ) {
if ( registry[module] !== undefined &&
registry[module].version !== undefined ) {
@@ -1581,14 +1602,15 @@
},
/**
- * @deprecated since 1.18 use
mw.loader.getVersion() instead
+ * @inheritdoc #getVersion
+ * @deprecated since 1.18 use #getVersion
instead
*/
version: function () {
return mw.loader.getVersion.apply(
mw.loader, arguments );
},
/**
- * Gets the state of a module
+ * Get the state of a module.
*
* @param {string} module name of module to get
state for
*/
@@ -1611,7 +1633,8 @@
},
/**
- * For backwards-compatibility with
Squid-cached pages. Loads mw.user
+ * For backwards-compatibility with
Squid-cached pages.
+ * Loads the `mediawiki.user` module.
*/
go: function () {
mw.loader.load( 'mediawiki.user' );
@@ -1781,6 +1804,8 @@
var lists = {};
/**
+ * Create an instance of mw.hook.
+ *
* @method hook
* @member mw
* @param {string} name Name of hook.
--
To view, visit https://gerrit.wikimedia.org/r/67648
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I5d241e4284f07a6be271c04cec3a5833dbaeed91
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/core
Gerrit-Branch: master
Gerrit-Owner: Krinkle <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
