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

@@ -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"

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):

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) {

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
+

toolkit/components/pictureinpicture/docs/picture-in-picture-api.rst

@@ -0,0 +1,4 @@
+PictureInPicture Reference
+===========================
+.. js:autoclass:: PictureInPicture
+  :members:

toolkit/components/pictureinpicture/docs/player-api.rst

@@ -0,0 +1,4 @@
+Player Reference
+======================
+.. js:autoclass:: Player
+  :members: