Merge "doc: Document gateway modules"

src/container.js

@@ -12,10 +12,9 @@ module.exports = function createContainer() {
 		cache = {};
 
 	/**
-	 * @interface Container
-	 *
 	 * The interface implemented by all service containers.
 	 *
+	 * @interface Container
 	 * @global
 	 */
 	return {

src/gateway/index.js

@@ -1,18 +1,22 @@
+// Note that this interface definition is in the global scope.
 /**
- * Interface for API gateway that fetches page summary
+ * The interface implemented by all preview gateways.
  *
- * @interface ext.popups.Gateway
+ * @interface Gateway
  */
 
 /**
- * Returns a preview model fetched from the api
+ * Fetches a preview for a page.
+ *
+ * If the underlying request is successful and contains data about the page,
+ * then the resulting promise will resolve. If not, then it will reject.
+ *
  * @function
- * @name ext.popups.Gateway#getPageSummary
- * @param {String} title Page title we're querying
- * @returns {jQuery.Promise} that resolves with {ext.popups.PreviewModel}
- * if the request is successful and the response is not empty; otherwise
- * it rejects.
+ * @name Gateway#getPageSummary
+ * @param {String} title The title of the page
+ * @returns {jQuery.Promise<PreviewModel>}
  */
+
 module.exports = {
 	createMediaWikiApiGateway: require( './mediawiki' ),
 	createRESTBaseGateway: require( './rest' )

src/gateway/mediawiki.js

@@ -1,19 +1,39 @@
+/**
+ * @module gateway/mediawiki
+ */
+
+/**
+ * @interface MediaWikiGateway
+ * @extends Gateway
+ *
+ * @global
+ */
+
 // Public and private cache lifetime (5 minutes)
+//
+// FIXME: Move this to src/constants.js.
 var CACHE_LIFETIME = 300,
 	createModel = require( '../preview/model' ).createModel;
 
 /**
- * MediaWiki API gateway factory
+ * Creates an instance of the MediaWiki API gateway.
  *
  * @param {mw.Api} api
- * @param {mw.ext.constants} config
- * @returns {ext.popups.Gateway}
+ * @param {Object} config Configuration that affects the major behavior of the
+ *  gateway.
+ * @param {Number} config.THUMBNAIL_SIZE The length of the major dimension of
+ *  the thumbnail.
+ * @param {Number} config.EXTRACT_LENGTH The maximum length, in characters,
+ *  of the extract.
+ * @returns {MediaWikiGateway}
  */
-function createMediaWikiApiGateway( api, config ) {
+module.exports = function createMediaWikiApiGateway( api, config ) {
 
 	/**
-	 * Fetch page data from the API
+	 * Fetches page data from the API.
 	 *
+	 * @function
+	 * @name MediaWikiGateway#fetch
 	 * @param {String} title
 	 * @return {jQuery.Promise}
 	 */
@@ -46,12 +66,6 @@ function createMediaWikiApiGateway( api, config ) {
 		} );
 	}
 
-	/**
-	 * Get the page summary from the api and transform the data
-	 *
-	 * @param {String} title
-	 * @returns {jQuery.Promise<ext.popups.PreviewModel>}
-	 */
 	function getPageSummary( title ) {
 		return fetch( title )
 			.then( extractPageFromResponse )
@@ -64,14 +78,16 @@ function createMediaWikiApiGateway( api, config ) {
 		convertPageToModel: convertPageToModel,
 		getPageSummary: getPageSummary
 	};
-}
+};
 
 /**
- * Extract page data from the MediaWiki API response
+ * Extracts page data from the API response.
  *
- * @param {Object} data API response data
- * @throws {Error} Throw an error if page data cannot be extracted,
- * i.e. if the response is empty,
+ * @function
+ * @name MediaWikiGateway#extractPageFromResponse
+ * @param {Object} data The response
+ * @throws {Error} If the response is empty or doesn't contain data about the
+ *  page
  * @returns {Object}
  */
 function extractPageFromResponse( data ) {
@@ -87,10 +103,12 @@ function extractPageFromResponse( data ) {
 }
 
 /**
- * Transform the MediaWiki API response to a preview model
+ * Converts the API response to a preview model.
  *
+ * @function
+ * @name MediaWikiGateway#convertPageToModel
  * @param {Object} page
- * @returns {ext.popups.PreviewModel}
+ * @returns {PreviewModel}
  */
 function convertPageToModel( page ) {
 	return createModel(
@@ -102,5 +120,3 @@ function convertPageToModel( page ) {
 		page.thumbnail
 	);
 }
-
-module.exports = createMediaWikiApiGateway;

src/gateway/rest.js

@@ -1,3 +1,7 @@
+/**
+ * @module gateway/rest
+ */
+
 var RESTBASE_ENDPOINT = '/api/rest_v1/page/summary/',
 	RESTBASE_PROFILE = 'https://www.mediawiki.org/wiki/Specs/Summary/1.0.0',
 	createModel = require( '../preview/model' ).createModel,
@@ -5,17 +9,36 @@ var RESTBASE_ENDPOINT = '/api/rest_v1/page/summary/',
 	$ = jQuery;
 
 /**
- * RESTBase gateway factory
+ * @interface RESTBaseGateway
+ * @extends Gateway
  *
- * @param {Function} ajax function from jQuery for example
- * @param {ext.popups.constants} config set of configuration values
- * @returns {ext.popups.Gateway}
+ * @global
  */
-function createRESTBaseGateway( ajax, config ) {
+
+/**
+ * Creates an instance of the RESTBase gateway.
+ *
+ * This gateway differs from the {@link MediaWikiGateway MediaWiki gateway} in
+ * that it fetches page data from [the RESTBase page summary endpoint][0].
+ *
+ * [0]: https://en.wikipedia.org/api/rest_v1/#!/Page_content/get_page_summary_title
+ *
+ * @param {Function} ajax A function with the same signature as `jQuery.ajax`
+ * @param {Object} config Configuration that affects the major behavior of the
+ *  gateway.
+ * @param {Number} config.THUMBNAIL_SIZE The length of the major dimension of
+ *  the thumbnail.
+ * @returns {RESTBaseGateway}
+ */
+module.exports = function createRESTBaseGateway( ajax, config ) {
 
 	/**
-	 * Fetch page data from the API
+	 * Fetches page data from [the RESTBase page summary endpoint][0].
 	 *
+	 * [0]: https://en.wikipedia.org/api/rest_v1/#!/Page_content/get_page_summary_title
+	 *
+	 * @function
+	 * @name MediaWikiGateway#fetch
 	 * @param {String} title
 	 * @return {jQuery.Promise}
 	 */
@@ -29,15 +52,6 @@ function createRESTBaseGateway( ajax, config ) {
 		} );
 	}
 
-	/**
-	 * Get the page summary from the api and transform the data
-	 *
-	 * Do not treat 404 as a failure as we want to show a generic
-	 * preview for missing pages.
-	 *
-	 * @param {String} title
-	 * @returns {jQuery.Promise<ext.popups.PreviewModel>}
-	 */
 	function getPageSummary( title ) {
 		var result = $.Deferred();
 
@@ -71,7 +85,7 @@ function createRESTBaseGateway( ajax, config ) {
 		convertPageToModel: convertPageToModel,
 		getPageSummary: getPageSummary
 	};
-}
+};
 
 /**
  * Resizes the thumbnail to the requested width, preserving its aspect ratio.
@@ -85,7 +99,7 @@ function createRESTBaseGateway( ajax, config ) {
  *
  * @param {Object} thumbnail The thumbnail image
  * @param {Object} original The original image
- * @param {int} thumbSize The requested size
+ * @param {Number} thumbSize The requested size
  * @returns {Object}
  */
 function generateThumbnailData( thumbnail, original, thumbSize ) {
@@ -127,11 +141,13 @@ function generateThumbnailData( thumbnail, original, thumbSize ) {
 }
 
 /**
- * Transform the rest API response to a preview model
+ * Converts the API response to a preview model.
  *
+ * @function
+ * @name RESTBaseGateway#convertPageToModel
  * @param {Object} page
- * @param {int} thumbSize
- * @returns {ext.popups.PreviewModel}
+ * @param {Number} thumbSize
+ * @returns {PreviewModel}
  */
 function convertPageToModel( page, thumbSize ) {
 	return createModel(
@@ -143,5 +159,3 @@ function convertPageToModel( page, thumbSize ) {
 		page.thumbnail ? generateThumbnailData( page.thumbnail, page.originalimage, thumbSize ) : undefined
 	);
 }
-
-module.exports = createRESTBaseGateway;