Document mediawiki.template

Bug: T352308
Change-Id: I6164c06cad08683295b7af138519979bf058b959

1 files changed, 51 insertions, 8 deletions

diff --git a/resources/src/mediawiki.template.js b/resources/src/mediawiki.template.js
index 2da53f1d7d5a..07ffbcb3a8f7 100644
--- a/resources/src/mediawiki.template.js
+++ b/resources/src/mediawiki.template.js
@@ -1,6 +1,47 @@
 /**
- * @class mw.template
- * @singleton
+ * An extensible library for rendering templates in different template languages.
+ * By default only the `html` template library is provided.
+ * The Mustache library is also provided in mediawiki core via the mediawiki.template.mustache library.
+ * @example
+ * // returns $( '<div>hello world</div>' );
+ * const $node = mw.template.compile( '<div>hello world</div>', 'html' ).render();
+ *
+ * // also returns $( '<div>hello world</div>' );
+ * mw.loader.using( 'mediawiki.template.mustache' ).then( () => {
+ *   const $node = mw.template.compile( '<div>{{ >Foo }}</div>', 'mustache' ).render( {
+ *     text: 'Hello world'
+ *   }, {
+ *     Foo: mw.template.compile( '{{text}}', 'mustache' )
+ *   } );
+ * } );
+ * @namespace mw.template
+ */
+
+/**
+ * Compiles a template for rendering.
+ *
+ * @typedef {Function} mw.template~TemplateCompileFunction
+ * @param {string} src source of the template
+ * @return {TemplateRenderer} for rendering
+ */
+
+/**
+ * Renders the template to create a jQuery object.
+ *
+ * @typedef {Function} mw.template~TemplateRenderFunction
+ * @param {Object} [data] for the template
+ * @param {Object} [partials] additional partial templates
+ * @return {jQuery}
+ */
+
+/**
+ * @typedef {Object} mw.template~TemplateRenderer
+ * @property {TemplateRenderFunction} render
+ */
+
+/**
+ * @typedef {Object} mw.template~TemplateCompiler
+ * @property {TemplateCompileFunction} compile
  */
 ( function () {
 	var compiledTemplates = {},
@@ -16,7 +57,7 @@
 		 * The compiler name must correspond with the name suffix of templates that use this compiler.
 		 *
 		 * @param {string} name Compiler name
-		 * @param {Object} compiler
+		 * @param {TemplateCompiler} compiler
 		 */
 		registerCompiler: function ( name, compiler ) {
 			if ( !compiler.compile ) {
@@ -43,7 +84,8 @@
 		 * Get a compiler via its name.
 		 *
 		 * @param {string} name Name of a compiler
-		 * @return {Object} The compiler
+		 * @return {TemplateCompiler} The compiler
+		 * @throws {Error} when unknown compiler provided
 		 */
 		getCompiler: function ( name ) {
 			var compiler = compilers[ name ];
@@ -61,7 +103,7 @@
 		 * @param {string} moduleName Name of the ResourceLoader module the template is associated with
 		 * @param {string} templateName Name of the template (including suffix)
 		 * @param {string} templateBody Contents of the template (e.g. html markup)
-		 * @return {Object} Compiled template
+		 * @return {TemplateRenderer} Compiled template
 		 */
 		add: function ( moduleName, templateName, templateBody ) {
 			// Precompile and add to cache
@@ -79,7 +121,7 @@
 		 *
 		 * @param {string} moduleName Name of the module to retrieve the template from
 		 * @param {string} templateName Name of template to be retrieved
-		 * @return {Object} Compiled template
+		 * @return {TemplateRenderer} Compiled template
 		 */
 		get: function ( moduleName, templateName ) {
 			var moduleTemplates;
@@ -102,8 +144,9 @@
 		 * Compile a string of template markup with an engine of choice.
 		 *
 		 * @param {string} templateBody Template body
-		 * @param {string} compilerName The name of a registered compiler
-		 * @return {Object} Compiled template
+		 * @param {string} compilerName The name of a registered compiler.
+		 * @return {TemplateRenderer} Compiled template
+		 * @throws {Error} when unknown compiler name provided.
 		 */
 		compile: function ( templateBody, compilerName ) {
 			return this.getCompiler( compilerName ).compile( templateBody );