From e006ae203d923ebeab225076c595e5f539b4e9a0 Mon Sep 17 00:00:00 2001 From: Tony Froman Date: Fri, 26 Mar 2021 21:55:19 +0000 Subject: [PATCH] Bug 1674152 - Building documentation for Picture-in-Picture using SphinxJS r=mtigley Changed formatting to support parsing, adding config files to target for parsing by SphinxJS via mach docs command. Differential Revision: https://phabricator.services.mozilla.com/D105061 --- docs/conf.py | 2 + .../pictureinpicture/PictureInPicture.jsm | 63 ++++++++++------ .../pictureinpicture/content/player.js | 74 +++++++++++++------ .../pictureinpicture/docs/index.rst | 9 +++ .../docs/picture-in-picture-api.rst | 4 + .../pictureinpicture/docs/player-api.rst | 4 + 6 files changed, 112 insertions(+), 44 deletions(-) create mode 100644 toolkit/components/pictureinpicture/docs/picture-in-picture-api.rst create mode 100644 toolkit/components/pictureinpicture/docs/player-api.rst diff --git a/docs/conf.py b/docs/conf.py index 9060d6723b12..4a5ca8069ec4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -63,6 +63,8 @@ js_source_path = [ "../toolkit/components/featuregates", "../toolkit/mozapps/extensions", "../toolkit/components/prompts/src", + "../toolkit/components/pictureinpicture", + "../toolkit/components/pictureinpicture/content", ] root_for_relative_js_paths = ".." jsdoc_config_path = "jsdoc.json" diff --git a/toolkit/components/pictureinpicture/PictureInPicture.jsm b/toolkit/components/pictureinpicture/PictureInPicture.jsm index 936d2fb16dfe..c10c1a97a23b 100644 --- a/toolkit/components/pictureinpicture/PictureInPicture.jsm +++ b/toolkit/components/pictureinpicture/PictureInPicture.jsm @@ -140,7 +140,6 @@ class PictureInPictureParent extends JSWindowActorParent { * This module is responsible for creating a Picture in Picture window to host * a clone of a video element running in web content. */ - var PictureInPicture = { // Maps PictureInPictureParent actors to their corresponding PiP player windows weakPipToWin: new WeakMap(), @@ -151,7 +150,7 @@ var PictureInPicture = { /** * Returns the player window if one exists and if it hasn't yet been closed. * - * @param pipActorRef (PictureInPictureParent) + * @param {PictureInPictureParent} pipActorRef * Reference to the calling PictureInPictureParent actor * * @return {DOM Window} the player window if it exists and is not in the @@ -188,6 +187,8 @@ var PictureInPicture = { /** * Called when the browser UI handles the View:PictureInPicture command via * the keyboard. + * + * @param {Event} event */ onCommand(event) { if (!Services.prefs.getBoolPref(PIP_ENABLED_PREF, false)) { @@ -218,7 +219,7 @@ var PictureInPicture = { /** * Remove attribute which enables pip icon in tab * - * @param window {Window} + * @param {Window} window * A PictureInPicture player's window, used to resolve the player's * associated originating content browser */ @@ -249,7 +250,7 @@ var PictureInPicture = { /** * Closes and waits for passed PiP player window to finish closing. * - * @param pipWin {Window} + * @param {Window} pipWin * Player window to close */ async closePipWindow(pipWin) { @@ -317,11 +318,11 @@ var PictureInPicture = { * A request has come up from content to open a Picture in Picture * window. * - * @param wgp (WindowGlobalParent) + * @param {WindowGlobalParent} wgps * The WindowGlobalParent that is requesting the Picture in Picture * window. * - * @param videoData (object) + * @param {object} videoData * An object containing the following properties: * * videoHeight (int): @@ -330,7 +331,7 @@ var PictureInPicture = { * videoWidth (int): * The preferred width of the video. * - * @returns Promise + * @returns {Promise} * Resolves once the Picture in Picture window has been created, and * the player component inside it has finished loading. */ @@ -380,6 +381,8 @@ var PictureInPicture = { /** * unload event has been called in player.js, cleanup our preserved * browser object. + * + * @param {Window} window */ unload(window) { TelemetryStopwatch.finish( @@ -403,11 +406,11 @@ var PictureInPicture = { * Open a Picture in Picture window on the same screen as parentWin, * sized based on the information in videoData. * - * @param parentWin (chrome window) + * @param {ChromeWindow} parentWin * The window hosting the browser that requested the Picture in * Picture window. * - * @param videoData (object) + * @param {object} videoData * An object containing the following properties: * * videoHeight (int): @@ -416,10 +419,10 @@ var PictureInPicture = { * videoWidth (int): * The preferred width of the video. * - * @param actorReference (PictureInPictureParent) + * @param {PictureInPictureParent} actorReference * Reference to the calling PictureInPictureParent * - * @returns Promise + * @returns {Promise} * Resolves once the window has opened and loaded the player component. */ async openPipWindow(parentWin, videoData) { @@ -461,13 +464,13 @@ var PictureInPicture = { * and size. If those values are unknown or offscreen, then a default * location and size is used. * - * @param requestingWin (chrome window|player window) + * @param {ChromeWindow|PlayerWindow} requestingWin * The window hosting the browser that requested the Picture in * Picture window. If this is an existing player window then the returned * player size and position will be determined based on the existing * player window's size and position. * - * @param videoData (object) + * @param {object} videoData * An object containing the following properties: * * videoHeight (int): @@ -476,7 +479,7 @@ var PictureInPicture = { * videoWidth (int): * The preferred width of the video. * - * @returns (object) + * @returns {object} * The size and position for the player window. * * top (int): @@ -654,6 +657,14 @@ var PictureInPicture = { return { top, left, width, height }; }, + /** + * Resizes the the PictureInPicture player window. + * + * @param {object} videoData + * The source video's data. + * @param {PictureInPictureParent} actorRef + * Reference to the PictureInPicture parent actor. + */ resizePictureInPictureWindow(videoData, actorRef) { let win = this.getWeakPipPlayer(actorRef); @@ -666,6 +677,13 @@ var PictureInPicture = { win.moveTo(left, top); }, + /** + * Opens the context menu for toggling PictureInPicture. + * + * @param {Window} window + * @param {object} data + * Message data from the PictureInPictureToggleParent + */ openToggleContextMenu(window, data) { let document = window.document; let popup = document.getElementById("pictureInPictureToggleContextMenu"); @@ -702,10 +720,10 @@ var PictureInPicture = { /** * This function takes a screen and will return the left, top, width and * height of the screen - * @param screen + * @param {Screen} screen * The screen we need to get the sizec and coordinates of * - * @returns array + * @returns {array} * Size and location of screen * * screenLeft.value (int): @@ -759,14 +777,17 @@ var PictureInPicture = { /** * This function takes in a left and top value and returns the screen they * are located on. + * * If the left and top are not on any screen, it will return the * default screen - * @param left + * + * @param {int} left * left or x coordinate - * @param top + * + * @param {int} top * top or y coordinate * - * @returns screen + * @returns {Screen} screen * the screen the left and top are on otherwise, default screen */ getWorkingScreen(left, top, width = 1, height = 1) { @@ -784,7 +805,7 @@ var PictureInPicture = { /** * Saves position and size of Picture-in-Picture window - * @param win The Picture-in-Picture window + * @param {Window} win The Picture-in-Picture window */ savePosition(win) { let xulStore = Services.xulStore; @@ -802,7 +823,7 @@ var PictureInPicture = { /** * Load last Picture in Picture location and size - * @returns object + * @returns {object} * The size and position of the last Picture in Picture window. * * top (int): diff --git a/toolkit/components/pictureinpicture/content/player.js b/toolkit/components/pictureinpicture/content/player.js index 8aeb91bbfe24..88d15b250169 100644 --- a/toolkit/components/pictureinpicture/content/player.js +++ b/toolkit/components/pictureinpicture/content/player.js @@ -36,11 +36,11 @@ const BOTTOM_RIGHT_QUADRANT = 4; * Public function to be called from PictureInPicture.jsm. This is the main * entrypoint for initializing the player window. * - * @param id (Number) + * @param {Number} id * A unique numeric ID for the window, used for Telemetry Events. - * @param wgp (WindowGlobalParent) + * @param {WindowGlobalParent} wgp * The WindowGlobalParent that is hosting the originating video. - * @param videoRef {ContentDOMReference} + * @param {ContentDOMReference} videoRef * A reference to the video element that a Picture-in-Picture window * is being created for */ @@ -52,7 +52,7 @@ function setupPlayer(id, wgp, videoRef) { * Public function to be called from PictureInPicture.jsm. This update the * controls based on whether or not the video is playing. * - * @param isPlaying (Boolean) + * @param {Boolean} isPlaying * True if the Picture-in-Picture video is playing. */ function setIsPlayingState(isPlaying) { @@ -63,7 +63,7 @@ function setIsPlayingState(isPlaying) { * Public function to be called from PictureInPicture.jsm. This update the * controls based on whether or not the video is muted. * - * @param isMuted (Boolean) + * @param {Boolean} isMuted * True if the Picture-in-Picture video is muted. */ function setIsMutedState(isMuted) { @@ -117,11 +117,11 @@ let Player = { /** * Initializes the player browser, and sets up the initial state. * - * @param id (Number) + * @param {Number} id * A unique numeric ID for the window, used for Telemetry Events. - * @param wgp (WindowGlobalParent) + * @param {WindowGlobalParent} wgp * The WindowGlobalParent that is hosting the originating video. - * @param videoRef {ContentDOMReference} + * @param {ContentDOMReference} videoRef * A reference to the video element that a Picture-in-Picture window * is being created for */ @@ -427,6 +427,10 @@ let Player = { ); }, + /** + * Uses the PiP window's change in position to determine which direction + * the window has been moved in. + */ determineDirectionDragged() { // Determine change in window location. let deltaX = this.oldMouseUpWindowX - window.screenX; @@ -445,6 +449,12 @@ let Player = { return dragDirection; }, + /** + * Event handler for "mouseup" events on the PiP window. + * + * @param {Event} event + * Event context details + */ onMouseUp(event) { if ( window.screenX != this.lastScreenX || @@ -536,11 +546,23 @@ let Player = { this.oldMouseUpWindowY = window.screenY; }, + /** + * Event handler for resizing the PiP Window + * + * @param {Event} event + * Event context data object + */ onResize(event) { this.resizeDebouncer.disarm(); this.resizeDebouncer.arm(); }, + /** + * Event handler for user issued commands + * + * @param {Event} event + * Event context data object + */ onCommand(event) { this.closePipWindow({ reason: "player-shortcut" }); }, @@ -552,18 +574,17 @@ let Player = { _isPlaying: false, /** - * isPlaying returns true if the video is currently playing. + * GET isPlaying returns true if the video is currently playing. * - * @return Boolean + * SET isPlaying to true if the video is playing, false otherwise. This will + * update the internal state and displayed controls. + * + * @type {Boolean} */ get isPlaying() { return this._isPlaying; }, - /** - * Set isPlaying to true if the video is playing, false otherwise. This will - * update the internal state and displayed controls. - */ set isPlaying(isPlaying) { this._isPlaying = isPlaying; this.controls.classList.toggle("playing", isPlaying); @@ -574,18 +595,17 @@ let Player = { _isMuted: false, /** - * isMuted returns true if the video is currently muted. + * GET isMuted returns true if the video is currently muted. * - * @return Boolean + * SET isMuted to true if the video is muted, false otherwise. This will + * update the internal state and displayed controls. + * + * @type {Boolean} */ get isMuted() { return this._isMuted; }, - /** - * Set isMuted to true if the video is muted, false otherwise. This will - * update the internal state and displayed controls. - */ set isMuted(isMuted) { this._isMuted = isMuted; this.controls.classList.toggle("muted", isMuted); @@ -594,6 +614,14 @@ let Player = { document.l10n.setAttributes(audioButton, strId); }, + /** + * Used for recording telemetry in Picture-in-Picture. + * + * @param {string} type + * The type of PiP event being recorded. + * @param {object} args + * The data to pass to telemetry when the event is recorded. + */ recordEvent(type, args) { Services.telemetry.recordEvent( "pictureinpicture", @@ -607,7 +635,7 @@ let Player = { /** * Makes the player controls visible. * - * @param revealIndefinitely (Boolean) + * @param {Boolean} revealIndefinitely * If false, this will hide the controls again after * CONTROLS_FADE_TIMEOUT_MS milliseconds has passed. If true, the controls * will remain visible until revealControls is called again with @@ -633,9 +661,9 @@ let Player = { * impose a minimum window size. For other platforms, this function is a * no-op. * - * @param width (Number) + * @param {Number} width * The width of the video being played. - * @param height (Number) + * @param {Number} height * The height of the video being played. */ computeAndSetMinimumSize(width, height) { diff --git a/toolkit/components/pictureinpicture/docs/index.rst b/toolkit/components/pictureinpicture/docs/index.rst index 81984c2b9479..324894c0d1e3 100644 --- a/toolkit/components/pictureinpicture/docs/index.rst +++ b/toolkit/components/pictureinpicture/docs/index.rst @@ -188,3 +188,12 @@ If ``video`` is being cloned visually to another element, calling this method wi boolean video.isCloningElementVisually; A read-only value that returns ``true`` if ``video`` is being cloned visually. + +API References +==================================== +.. toctree:: + :maxdepth: 1 + + picture-in-picture-api + player-api + diff --git a/toolkit/components/pictureinpicture/docs/picture-in-picture-api.rst b/toolkit/components/pictureinpicture/docs/picture-in-picture-api.rst new file mode 100644 index 000000000000..ce46875ef026 --- /dev/null +++ b/toolkit/components/pictureinpicture/docs/picture-in-picture-api.rst @@ -0,0 +1,4 @@ +PictureInPicture Reference +=========================== +.. js:autoclass:: PictureInPicture + :members: diff --git a/toolkit/components/pictureinpicture/docs/player-api.rst b/toolkit/components/pictureinpicture/docs/player-api.rst new file mode 100644 index 000000000000..8e7abf574b8d --- /dev/null +++ b/toolkit/components/pictureinpicture/docs/player-api.rst @@ -0,0 +1,4 @@ +Player Reference +====================== +.. js:autoclass:: Player + :members: \ No newline at end of file