From: Timo Tijhof <krinklemail@gmail.com>
Date: Wed, 2 Sep 2015 13:54:23 +0000 (+0200)
Subject: resourceloader: Document mw.loader state machine
X-Git-Tag: 1.31.0-rc.0~10142^2
X-Git-Url: http://git.cyclocoop.org///%22%40url%40//%22?a=commitdiff_plain;h=1c9acfcd2db9c2486f4aa6449c22cf89d103655d;p=lhc%2Fweb%2Fwiklou.git

resourceloader: Document mw.loader state machine

Change-Id: I5d40a6d30805a10e638e94e9d179a0db1af2126c
---

diff --git a/resources/src/mediawiki/mediawiki.js b/resources/src/mediawiki/mediawiki.js
index a73accf51b..e110f90bed 100644
--- a/resources/src/mediawiki/mediawiki.js
+++ b/resources/src/mediawiki/mediawiki.js
@@ -718,7 +718,7 @@
 			 *
 			 *     {
 			 *         'moduleName': {
-			 *             // From mw.loader.register() in startup module
+			 *             // From mw.loader.register()
 			 *             'version': '########' (hash)
 			 *             'dependencies': ['required.foo', 'bar.also', ...], (or) function () {}
 			 *             'group': 'somegroup', (or) null
@@ -736,6 +736,31 @@
 			 *         }
 			 *     }
 			 *
+			 * State machine:
+			 *
+			 * - `registered`:
+			 *    The module is known to the system but not yet requested.
+			 *    Meta data is registered via mw.loader#register. Calls to that method are
+			 *    generated server-side by the startup module.
+			 * - `loading` (1):
+			 *    The module is requested through mw.loader (either directly or as dependency of
+			 *    another module). The client will be fetching module contents from the server.
+			 *    The contents are then stashed in the registry via mw.loader#implement.
+			 * - `loaded`:
+			 *    The module has been requested from the server and stashed via mw.loader#implement.
+			 *    If the module has no more dependencies in-fight, the module will be executed
+			 *    right away. Otherwise execution is deferred, controlled via #handlePending.
+			 * - `loading` (2):
+			 *    The module is being executed.
+			 *    TODO: Create a new state instead of re-using the "loading" state.
+			 * - `ready`:
+			 *    The module has been successfully executed.
+			 * - `error`:
+			 *    The module (or one of its dependencies) produced an error during execution.
+			 * - `missing`:
+			 *    The module was registered client-side and requested, but the server denied knowledge
+			 *    of the module's existence.
+			 *
 			 * @property
 			 * @private
 			 */