Merge "jsdoc: Restrict Popups documentation to public facing APIs"

src/actionTypes.js

@@ -1,7 +1,7 @@
 /**
  * @module actionTypes
+ * @private
  */
-
 export default {
 	BOOT: 'BOOT',
 	LINK_DWELL: 'LINK_DWELL',

src/actions.js

@@ -1,12 +1,11 @@
-/**
- * @module actions
- */
-
 import types from './actionTypes';
 import wait from './wait';
 import { createNullModel, previewTypes, getDwellDelay } from './preview/model';
 import { FETCH_START_DELAY, PREVIEW_SEEN_DURATION, ABANDON_END_DELAY } from './constants';
-
+/**
+ * @module actions
+ * @private
+ */
 /**
  * Mixes in timing information to an action.
  *
@@ -91,6 +90,7 @@ export function registerSetting( name, enabled ) {
 /**
  * Represents Page Previews fetching data via the gateway.
  *
+ * @private
  * @param {Gateway} gateway
  * @param {mw.Title} title
  * @param {HTMLAnchorElement} el
@@ -189,6 +189,7 @@ export function fetch( gateway, title, el, token, type ) {
  * Represents the user dwelling on a link, either by hovering over it with
  * their mouse or by focussing it using their keyboard or an assistive device.
  *
+ * @private
  * @param {mw.Title} title
  * @param {HTMLAnchorElement} el
  * @param {ext.popups.Measures} measures
@@ -250,6 +251,7 @@ export function linkDwell( title, el, measures, gateway, generateToken, type ) {
  * an assistive device, or abandoning a preview by moving their mouse away
  * from it.
  *
+ * @private
  * @return {Redux.Thunk}
  */
 export function abandon() {
@@ -402,6 +404,7 @@ export function hideSettings() {
  * See docs/adr/0003-keep-enabled-state-only-in-preview-reducer.md for more
  * details.
  *
+ * @private
  * @param {Object} enabled Mapping preview type identifiers to boolean flags
  * @return {Redux.Thunk}
  */

src/bracketedPixelRatio.js

@@ -1,5 +1,6 @@
 /**
  * @module bracketedPixelRatio
+ * @private
  */
 
 /**

src/canSaveToUserPreferences.js

@@ -1,5 +1,6 @@
 /**
  * @module canSaveToUserPreferences
+ * @private
  */
 
 /**

src/changeListener.js

@@ -1,5 +1,6 @@
 /**
  * @module changeListener
+ * @private
  */
 
 /**

src/changeListeners/footerLink.js

@@ -1,5 +1,6 @@
 /**
  * @module changeListeners/footerLink
+ * @private
  */
 
 /**

src/changeListeners/pageviews.js

@@ -1,5 +1,6 @@
 /**
  * @module changeListeners/pageviews
+ * @private
  */
 
 /**

src/changeListeners/syncUserSettings.js

@@ -1,5 +1,6 @@
 /**
  * @module changeListeners/syncUserSettings
+ * @private
  */
 
 /**
@@ -37,7 +38,7 @@ export default function syncUserSettings( userSettings ) {
  *
  * @param {Object} state tree
  * @param {string} path dot-separated path in the state tree
- * @return {*}
+ * @return {any}
  */
 function get( state, path ) {
 	return path.split( '.' ).reduce(

src/container.js

@@ -1,5 +1,6 @@
 /**
  * @module container
+ * @private
  */
 
 /**
@@ -21,7 +22,7 @@ export default function createContainer() {
 		 * @method
 		 * @name Container#set
 		 * @param {string} name
-		 * @param {*} factory
+		 * @param {any} factory
 		 */
 		set( name, factory ) {
 			factories[ name ] = factory;
@@ -64,7 +65,7 @@ export default function createContainer() {
 		 * @method
 		 * @name Container#get
 		 * @param {string} name
-		 * @return {*}
+		 * @return {any}
 		 * @throws Error If the service hasn't been defined
 		 */
 		get( name ) {

src/counts.js

@@ -1,5 +1,6 @@
 /**
  * @module counts
+ * @private
  */
 
 /**

src/experiments.js

@@ -1,5 +1,6 @@
 /**
  * @module experiments
+ * @private
  */
 
 /**

src/formatter.js

@@ -1,5 +1,6 @@
 /**
  * @module formatter
+ * @private
  */
 
 /**

src/gateway/index.js

@@ -1,5 +1,6 @@
 /**
  * @module gateway
+ * @private
  */
 
 /**

src/gateway/mediawiki.js

@@ -1,11 +1,13 @@
-/**
- * @module gateway/mediawiki
- */
-
 import { createModel } from '../preview/model';
 import * as formatter from '../formatter';
 import { abortablePromise } from './index.js';
 
+/**
+ * @module gateway/mediawiki
+ * @private
+ * @ignore
+ */
+
 // Public and private cache lifetime (5 minutes)
 //
 // FIXME: Move this to src/constants.js.
@@ -20,6 +22,7 @@ const CACHE_LIFETIME = 300;
 /**
  * Creates an instance of the MediaWiki API gateway.
  *
+ * @ignore
  * @param {mw.Api} api
  * @param {Object} config Configuration that affects the major behavior of the
  *  gateway.

src/gateway/page.js

@@ -1,13 +1,13 @@
-/**
- * @module gateway/page
- */
-
 import constants from '../constants';
 import createMediaWikiApiGateway from './mediawiki';
 import createRESTBaseGateway from './rest';
 import * as formatters from './restFormatters';
 import { abortablePromise } from './index.js';
 
+/**
+ * @module gateway/page
+ * @private
+ */
 /**
  * @param {Object} options
  * @return {Promise}

src/gateway/rest.js

@@ -1,10 +1,9 @@
-/**
- * @module gateway/rest
- */
-
 import { createModel } from '../preview/model';
 import { abortablePromise } from './index.js';
-
+/**
+ * @module gateway/rest
+ * @private
+ */
 const RESTBASE_PROFILE = 'https://www.mediawiki.org/wiki/Specs/Summary/1.2.0';
 
 /** @typedef {function(JQuery.AjaxSettings=): JQuery.jqXHR} Ajax */
@@ -17,6 +16,8 @@ const RESTBASE_PROFILE = 'https://www.mediawiki.org/wiki/Specs/Summary/1.2.0';
  *
  * [0]: https://en.wikipedia.org/api/rest_v1/#!/Page_content/get_page_summary_title
  *
+ * @private
+ * @ignore
  * @param {Ajax} ajax A function with the same signature as `jQuery.ajax`
  * @param {Object} config Configuration that affects the major behavior of the
  *  gateway.
@@ -88,7 +89,7 @@ export default function createRESTBaseGateway( ajax, config, extractParser ) {
  * https://www.mediawiki.org/wiki/Help:Images#Supported_media_types_for_images
  *
  * @param {string} filename
- *
+ * @ignore
  * @return {boolean}
  */
 function isSafeImgFormat( filename ) {
@@ -169,6 +170,7 @@ function generateThumbnailData( thumbnail, original, thumbSize ) {
  * Converts the API response to a preview model.
  *
  * @method
+ * @ignore
  * @name RESTBaseGateway#convertPageToModel
  * @param {Object} page
  * @param {number} thumbSize

src/gateway/restFormatters.js

@@ -1,5 +1,6 @@
 /**
  * @module restFormatters
+ * @private
  */
 
 import * as formatter from '../formatter';

src/index.js

@@ -1,7 +1,3 @@
-/**
- * @module popups
- */
-
 import * as Redux from 'redux';
 import * as ReduxThunk from 'redux-thunk';
 
@@ -26,7 +22,10 @@ import { previewTypes, getPreviewType,
 import setUserConfigFlags from './setUserConfigFlags';
 import { registerGatewayForPreviewType, getGatewayForPreviewType } from './gateway';
 import { FETCH_START_DELAY, FETCH_COMPLETE_TARGET_DELAY } from './constants';
-
+/**
+ * @module popups
+ * @private
+ */
 const EXCLUDED_LINK_SELECTORS = [
 	'.extiw',
 	// ignore links that point to the same article

src/instrumentation/statsv.js

@@ -1,5 +1,6 @@
 /**
  * @module instrumentation/statsv
+ * @private
  */
 
 /**

src/integrations/mwpopups.js

@@ -1,10 +1,13 @@
 /**
- * @module MediaWiki-Popups-Integration
+ * The public facing MediaWiki Popups API.
+ *
+ * @module mw.popups
  */
 
 import { previewTypes } from '../preview/model';
 
 /**
+ * @private
  * @param {string} type
  * @return {boolean} whether the preview type supports being disabled/enabled.
  */
@@ -16,6 +19,7 @@ function canShowSettingForPreviewType( type ) {
  * This function provides a mw.popups object which can be used by 3rd party
  * to interact with Popups.
  *
+ * @ignore
  * @param {Redux.Store} store Popups store
  * @param {Function} registerModel allows extensions to register custom preview handlers.
  * @param {Function} registerPreviewUI allows extensions to register custom preview renderers.
@@ -46,6 +50,7 @@ export default function createMwPopups( store, registerModel, registerPreviewUI,
 		 * custom preview type will render the preview. If not provided default renderer is used.
 		 *
 		 * @typedef {Object} PopupModule
+		 * @private
 		 * @property {string} type A unique string for identifying the type of page preview
 		 * @property {string} selector A CSS selector which identifies elements that will display
 		 * this type of page preview
@@ -73,6 +78,7 @@ export default function createMwPopups( store, registerModel, registerPreviewUI,
 		 * ```
 		 *
 		 * @unstable
+		 * @private
 		 * @param {PopupModule} module
 		 */
 		register: function ( module ) {

src/isPagePreviewsEnabled.js

@@ -1,5 +1,6 @@
 /**
  * @module isPagePreviewsEnabled
+ * @private
  */
 import { previewTypes } from './preview/model';
 const canSaveToUserPreferences = require( './canSaveToUserPreferences.js' );

src/preview/model.js

@@ -1,5 +1,6 @@
 /**
  * @module preview/model
+ * @private
  */
 
 import { requiresSummary } from '../ui/renderer';

src/previewBehavior.js

@@ -1,5 +1,6 @@
 /**
  * @module previewBehaviour
+ * @private
  */
 const canSaveToUserPreferences = require( './canSaveToUserPreferences.js' );
 

src/reducers/nextState.js

@@ -1,5 +1,6 @@
 /**
  * @module nextState
+ * @private
  */
 
 /**
@@ -52,7 +53,7 @@ export default function nextState( state, updates ) {
 }
 
 /**
- * @param {*} obj
+ * @param {any} obj
  * @return {boolean}
  */
 function isObject( obj ) {

src/reducers/pageviews.js

@@ -1,5 +1,6 @@
 /**
  * @module reducers/pageviews
+ * @private
  */
 
 import actionTypes from '../actionTypes';

src/setUserConfigFlags.js

@@ -1,5 +1,6 @@
 /**
  * @module setUserConfigFlags
+ * @private
  */
 
 /**

src/title.js

@@ -1,5 +1,6 @@
 /**
  * @module title
+ * @private
  */
 
 /**

src/ui/renderer.js

@@ -1,13 +1,12 @@
-/**
- * @module renderer
- */
-
 import wait from '../wait';
 import pointerMaskSVG from './pointer-mask.svg';
 import { SIZES, createThumbnail } from './thumbnail';
 import { renderPreview } from './templates/preview/preview';
 import { renderPagePreview } from './templates/pagePreview/pagePreview';
-
+/**
+ * @module renderer
+ * @private
+ */
 const landscapePopupWidth = 450,
 	portraitPopupWidth = 320,
 	pointerSize = 8, // Height of the pointer.
@@ -110,6 +109,7 @@ export function render( model ) {
 		 *
 		 * See `show` for more detail.
 		 *
+		 * @ignore
 		 * @param {Event} event
 		 * @param {Object} boundActions The
 		 *  [bound action creators](http://redux.js.org/docs/api/bindActionCreators.html)
@@ -130,6 +130,7 @@ export function render( model ) {
 		 *
 		 * See `hide` for more detail.
 		 *
+		 * @ignore
 		 * @return {jQuery.Promise<void>}
 		 */
 		hide() {
@@ -251,6 +252,8 @@ export function createDisambiguationPreview( model ) {
  * TODO: From the perspective of the client, there's no need to distinguish
  * between rendering and showing a preview. Merge #render and Preview#show.
  *
+ * @private
+ * @ignore
  * @param {ext.popups.Preview} preview
  * @param {ext.popups.Measures} measures
  * @param {HTMLElement} _link event target (unused)
@@ -670,7 +673,10 @@ export function getClosestYPosition( y, rects, isTop ) {
 }
 
 export const test = {
-	/** For testing only */
+	/**
+	 * For testing only
+	 * @private
+	 */
 	reset: () => {
 		renderers = {};
 	}

src/ui/settingsDialog.js

@@ -1,5 +1,6 @@
 /**
  * @module settingsDialog
+ * @private
  */
 
 import { renderSettingsDialog } from './templates/settingsDialog/settingsDialog';

src/ui/settingsDialogRenderer.js

@@ -1,7 +1,3 @@
-/**
- * @module settingsDialogRenderer
- */
-
 import { createSettingsDialog } from './settingsDialog';
 
 const initDialog = ( boundActions, previewTypesEnabled ) => {
@@ -24,11 +20,16 @@ const initDialog = ( boundActions, previewTypesEnabled ) => {
 	dialog.querySelector( '.close' ).addEventListener( 'click', boundActions.hideSettings );
 	return dialog;
 };
-
+/**
+ * @module settingsDialogRenderer
+ * @private
+ */
 /**
  * Creates a render function that will create the settings dialog and return
  * a set of methods to operate on it
  *
+ * @private
+ * @ignore
  * @return {Function} render function
  */
 export default function createSettingsDialogRenderer() {

src/ui/templates/pagePreview/pagePreview.js

@@ -1,5 +1,6 @@
 /**
  * @module pagePreview
+ * @private
  */
 
 import { renderPopup } from '../popup/popup';

src/ui/templates/popup/popup.js

@@ -1,5 +1,6 @@
 /**
  * @module popup
+ * @private
  */
 
 import { createNodeFromTemplate } from '../templateUtil';

src/ui/templates/preview/preview.js

@@ -1,5 +1,6 @@
 /**
  * @module preview
+ * @private
  */
 
 import { renderPopup } from '../popup/popup';

src/ui/templates/settingsDialog/settingsDialog.js

@@ -1,5 +1,6 @@
 /**
  * @module settingsDialog
+ * @private
  */
 
 import { escapeHTML } from '../templateUtil';

src/ui/templates/templateUtil.js

@@ -1,5 +1,6 @@
 /**
  * @module templateUtil
+ * @private
  */
 
 /**

src/ui/thumbnail.js

@@ -1,5 +1,6 @@
 /**
  * @module thumbnail
+ * @private
  */
 
 import constants from '../constants';

src/userSettings.js

@@ -2,6 +2,7 @@ import { previewTypes } from './preview/model';
 
 /**
  * @module userSettings
+ * @private
  */
 
 const PAGE_PREVIEWS_ENABLED_KEY = 'mwe-popups-enabled',

src/wait.js

@@ -1,5 +1,6 @@
 /**
  * @module wait
+ * @private
  */
 
 /**