Add/fix JSDoc comments

While reviewing "[PREVIEW|RN]: Handle getUserMedia in progress" I
discovered JSDoc comments which could be improved. They are not
necessarily 100% related to the PR.

react/features/base/conference/actions.js

@@ -211,12 +211,12 @@ export function conferenceLeft(conference: Object) {
 }
 
 /**
- * Attaches any pre-existing local media to the conference, before
- * the conference will be joined. Then signals the intention of the application
- * to have the local participant join a specific conference.
+ * Adds any existing local tracks to a specific conference before the conference
+ * is joined. Then signals the intention of the application to have the local
+ * participant join the specified conference.
  *
- * @param {JitsiConference} conference - The JitsiConference instance the
- * local participant will (try to) join.
+ * @param {JitsiConference} conference - The {@code JitsiConference} instance
+ * the local participant will (try to) join.
  * @returns {Function}
  */
 function _conferenceWillJoin(conference: Object) {

react/features/base/tracks/actionTypes.js

@@ -1,6 +1,6 @@
 /**
- * Action for when a track has been added to the conference,
- * local or remote.
+ * The type of redux action dispatched when a track has been (locally or
+ * remotely) added to the conference.
  *
  * {
  *     type: TRACK_ADDED,
@@ -10,18 +10,19 @@
 export const TRACK_ADDED = Symbol('TRACK_ADDED');
 
 /**
- * Action triggered when a local track starts being created through the WebRTC
- * getUserMedia call. It will include extra 'gumProcess' field which is
- * a Promise with extra 'cancel' method which can be used to cancel the process.
- * Canceling will result in disposing any JitsiLocalTrack returned by the GUM
- * callback. There will be TRACK_CREATE_CANCELED event instead of track
- * added/gum failed events.
+ * The type of redux action dispatched when a local track starts being created
+ * via a WebRTC {@code getUserMedia} call. The action's payload includes an
+ * extra {@code gumProcess} property which is a {@code Promise} with an extra
+ * {@code cancel} method which can be used to cancel the process. Canceling will
+ * result in disposing any {@code JitsiLocalTrack} returned by the
+ * {@code getUserMedia} callback. There will be a {@code TRACK_CREATE_CANCELED}
+ * action instead of a {@code TRACK_ADDED} or {@code TRACK_CREATE_ERROR} action.
  *
  * {
  *     type: TRACK_BEING_CREATED
  *     track: {
+ *         gumProcess: Promise with a `cancel` method to cancel the process,
  *         local: true,
- *         gumProcess: Promise with cancel() method to abort,
  *         mediaType: MEDIA_TYPE
  *     }
  * }
@@ -29,8 +30,9 @@ export const TRACK_ADDED = Symbol('TRACK_ADDED');
 export const TRACK_BEING_CREATED = Symbol('TRACK_BEING_CREATED');
 
 /**
- * Action sent when canceled GUM process completes either successfully or with
- * an error (error is ignored and track is immediately disposed if created).
+ * The type of redux action dispatched when a canceled {@code getUserMedia}
+ * process completes either successfully or with an error (the error is ignored
+ * and the track is immediately disposed if it has been created).
  *
  * {
  *     type: TRACK_CREATE_CANCELED,
@@ -40,7 +42,8 @@ export const TRACK_BEING_CREATED = Symbol('TRACK_BEING_CREATED');
 export const TRACK_CREATE_CANCELED = Symbol('TRACK_CREATE_CANCELED');
 
 /**
- * Action sent when GUM fails with an error other than permission denied.
+ * The type of redux action dispatched when {@code getUserMedia} fails with an
+ * error (such as permission denied).
  *
  * {
  *     type: TRACK_CREATE_ERROR,
@@ -51,8 +54,8 @@ export const TRACK_CREATE_CANCELED = Symbol('TRACK_CREATE_CANCELED');
 export const TRACK_CREATE_ERROR = Symbol('TRACK_CREATE_ERROR');
 
 /**
- * Action for when a track has been removed from the conference,
- * local or remote.
+ * The type of redux action dispatched when a track has been (locally or
+ * remotely) removed from the conference.
  *
  * {
  *     type: TRACK_REMOVED,
@@ -62,7 +65,7 @@ export const TRACK_CREATE_ERROR = Symbol('TRACK_CREATE_ERROR');
 export const TRACK_REMOVED = Symbol('TRACK_REMOVED');
 
 /**
- * Action for when a track properties were updated.
+ * The type of redux action dispatched when a track's properties were updated.
  *
  * {
  *     type: TRACK_UPDATED,

react/features/base/tracks/actions.js

@@ -37,7 +37,7 @@ export function createDesiredLocalTracks(...desiredTypes) {
             const { audio, video } = state['features/base/media'];
 
             audio.muted || desiredTypes.push(MEDIA_TYPE.AUDIO);
-            Boolean(video.muted) || desiredTypes.push(MEDIA_TYPE.VIDEO);
+            video.muted || desiredTypes.push(MEDIA_TYPE.VIDEO);
         }
 
         const availableTypes
@@ -85,44 +85,52 @@ export function createLocalTracksA(options = {}) {
                     .find(t => t.local && t.mediaType === device)) {
                 throw new Error(`Local track for ${device} already exists`);
             }
-            const gumProcess = createLocalTracksF(
-                {
-                    cameraDeviceId: options.cameraDeviceId,
-                    devices: [ device ],
-                    facingMode: options.facingMode || CAMERA_FACING_MODE.USER,
-                    micDeviceId: options.micDeviceId
-                },
-                /* firePermissionPromptIsShownEvent */ false,
-                store)
-            .then(
-                localTracks => {
-                    // Because GUM is called for 1 device (which is actually
-                    // a media type 'audio','video', 'screen' etc.) we should
-                    // not get more than one JitsiTrack.
-                    if (localTracks.length !== 1) {
-                        throw new Error(
-                            'Expected exactly 1 track, but was '
-                                + `given ${localTracks.length} tracks`
-                                + `for device: ${device}.`);
-                    }
 
-                    if (gumProcess.canceled) {
-                        return _disposeTracks(localTracks)
-                                    .then(
-                                        () =>
-                                            dispatch(
-                                                _trackCreateCanceled(device)));
-                    }
+            const gumProcess
+                = createLocalTracksF(
+                    {
+                        cameraDeviceId: options.cameraDeviceId,
+                        devices: [ device ],
+                        facingMode:
+                            options.facingMode || CAMERA_FACING_MODE.USER,
+                        micDeviceId: options.micDeviceId
+                    },
+                    /* firePermissionPromptIsShownEvent */ false,
+                    store)
+                .then(
+                    localTracks => {
+                        // Because GUM is called for 1 device (which is actually
+                        // a media type 'audio', 'video', 'screen', etc.) we
+                        // should not get more than one JitsiTrack.
+                        if (localTracks.length !== 1) {
+                            throw new Error(
+                                `Expected exactly 1 track, but was given ${
+                                    localTracks.length} tracks for device: ${
+                                    device}.`);
+                        }
 
-                    return dispatch(trackAdded(localTracks[0]));
-                },
-                // eslint-disable-next-line no-confusing-arrow
-                reason =>
-                    dispatch(
-                        gumProcess.canceled
-                            ? _trackCreateCanceled(device)
-                            : _onCreateLocalTracksRejected(reason, device)));
+                        if (gumProcess.canceled) {
+                            return _disposeTracks(localTracks)
+                                .then(() =>
+                                    dispatch(_trackCreateCanceled(device)));
+                        }
 
+                        return dispatch(trackAdded(localTracks[0]));
+                    },
+                    reason =>
+                        dispatch(
+                            gumProcess.canceled
+                                ? _trackCreateCanceled(device)
+                                : _onCreateLocalTracksRejected(
+                                    reason,
+                                    device)));
+
+            /**
+             * Cancels the {@code getUserMedia} process represented by this
+             * {@code Promise}.
+             *
+             * @returns {Promise} This {@code Promise} i.e. {@code gumProcess}.
+             */
             gumProcess.cancel = () => {
                 gumProcess.canceled = true;
 
@@ -132,8 +140,8 @@ export function createLocalTracksA(options = {}) {
             dispatch({
                 type: TRACK_BEING_CREATED,
                 track: {
-                    local: true,
                     gumProcess,
+                    local: true,
                     mediaType: device
                 }
             });
@@ -151,9 +159,9 @@ export function destroyLocalTracks() {
     return (dispatch, getState) => {
         // First wait until any getUserMedia in progress is settled and then get
         // rid of all local tracks.
-        _cancelAllGumInProgress(getState)
-            .then(
-                () => dispatch(
+        _cancelGUMProcesses(getState)
+            .then(() =>
+                dispatch(
                     _disposeAndRemoveTracks(
                         getState()['features/base/tracks']
                             .filter(t => t.local)
@@ -366,49 +374,27 @@ function _addTracks(tracks) {
 }
 
 /**
- * Signals that track create operation for given media track has been canceled.
- * Will clean up local track stub from the Redux state which holds the
- * 'gumProcess' reference.
- *
- * @param {MEDIA_TYPE} mediaType - The type of the media for which the track was
- * being created.
- * @returns {{
- *      type,
- *      trackType: MEDIA_TYPE
- * }}
- * @private
- */
-function _trackCreateCanceled(mediaType) {
-    return {
-        type: TRACK_CREATE_CANCELED,
-        trackType: mediaType
-    };
-}
-
-/**
- * Cancels and waits for any get user media operations currently in progress to
- * complete.
+ * Cancels and waits for any {@code getUserMedia} process/currently in progress
+ * to complete/settle.
  *
- * @param {Function} getState - The Redux store {@code getState} method used to
- * obtain the state.
- * @returns {Promise} - A Promise resolved once all {@code gumProcess.cancel}
- * Promises are settled. That is when they are either resolved or rejected,
- * because all we care about here is to be sure that get user media callbacks
- * have completed (returned from the native side).
+ * @param {Function} getState - The redux store {@code getState} function used
+ * to obtain the state.
  * @private
+ * @returns {Promise} - A {@code Promise} resolved once all
+ * {@code gumProcess.cancel()} {@code Promise}s are settled because all we care
+ * about here is to be sure that the {@code getUserMedia} callbacks have
+ * completed (i.e. returned from the native side).
  */
-function _cancelAllGumInProgress(getState) {
-    // FIXME use logger
+function _cancelGUMProcesses(getState) {
     const logError
         = error =>
-            console.error('gumProcess.cancel failed', JSON.stringify(error));
+            logger.error('gumProcess.cancel failed', JSON.stringify(error));
 
     return Promise.all(
         getState()['features/base/tracks']
             .filter(t => t.local)
-            .map(
-                t => t.gumProcess
-                    && t.gumProcess.cancel().catch(logError)));
+            .map(({ gumProcess }) =>
+                gumProcess && gumProcess.cancel().catch(logError)));
 }
 
 /**
@@ -421,15 +407,15 @@ function _cancelAllGumInProgress(getState) {
 export function _disposeAndRemoveTracks(tracks) {
     return dispatch =>
         _disposeTracks(tracks)
-            .then(
-                () => Promise.all(tracks.map(t => dispatch(trackRemoved(t)))));
+            .then(() =>
+                Promise.all(tracks.map(t => dispatch(trackRemoved(t)))));
 }
 
 /**
  * Disposes passed tracks.
  *
  * @param {(JitsiLocalTrack|JitsiRemoteTrack)[]} tracks - List of tracks.
- * @protected
+ * @private
  * @returns {Promise} - A Promise resolved once {@link JitsiTrack.dispose()} is
  * done for every track from the list.
  */
@@ -438,13 +424,12 @@ function _disposeTracks(tracks) {
         tracks.map(t =>
             t.dispose()
                 .catch(err => {
-                    // Track might be already disposed so ignore such an
-                    // error. Of course, re-throw any other error(s).
+                    // Track might be already disposed so ignore such an error.
+                    // Of course, re-throw any other error(s).
                     if (err.name !== JitsiTrackErrors.TRACK_IS_DISPOSED) {
                         throw err;
                     }
-                })
-        ));
+                })));
 }
 
 /**
@@ -496,7 +481,8 @@ function _onCreateLocalTracksRejected({ gum }, device) {
 }
 
 /**
- * Returns true if the provided JitsiTrack should be rendered as a mirror.
+ * Returns true if the provided {@code JitsiTrack} should be rendered as a
+ * mirror.
  *
  * We only want to show a video in mirrored mode when:
  * 1) The video source is local, and not remote.
@@ -524,3 +510,23 @@ function _shouldMirror(track) {
             // but that may not be the case tomorrow.
             && track.getCameraFacingMode() === CAMERA_FACING_MODE.USER);
 }
+
+/**
+ * Signals that track create operation for given media track has been canceled.
+ * Will clean up local track stub from the redux state which holds the
+ * {@code gumProcess} reference.
+ *
+ * @param {MEDIA_TYPE} mediaType - The type of the media for which the track was
+ * being created.
+ * @private
+ * @returns {{
+ *     type,
+ *     trackType: MEDIA_TYPE
+ * }}
+ */
+function _trackCreateCanceled(mediaType) {
+    return {
+        type: TRACK_CREATE_CANCELED,
+        trackType: mediaType
+    };
+}

react/features/base/tracks/functions.js

@@ -110,21 +110,21 @@ export function getLocalTrack(tracks, mediaType) {
 }
 
 /**
- * Returns an array containing local tracks. Local tracks without valid
- * JitsiTrack will not be included in the list.
+ * Returns an array containing the local tracks with a (valid)
+ * {@code JitsiTrack}.
  *
- * @param {Track[]} tracks - An array of all local tracks.
+ * @param {Track[]} tracks - An array containing all local tracks.
  * @returns {Track[]}
  */
 export function getLocalTracks(tracks) {
 
-    // XXX A local track is considered ready only once it has 'jitsiTrack' field
-    // set by the TRACK_ADDED action. Until then there is a stub added just
-    // before get user media call with a cancellable 'gumInProgress' field which
-    // then can be used to destroy the track that has not yet been added to
-    // the Redux store. Once GUM is cancelled it will never make it to the store
-    // nor there will be any TRACK_ADDED/TRACK_REMOVED related events fired for
-    // it.
+    // XXX A local track is considered ready only once it has its `jitsiTrack`
+    // property set by the `TRACK_ADDED` action. Until then there is a stub
+    // added just before the `getUserMedia` call with a cancellable
+    // `gumInProgress` property which then can be used to destroy the track that
+    // has not yet been added to the redux store. Once GUM is cancelled, it will
+    // never make it to the store nor there will be any
+    // `TRACK_ADDED`/`TRACK_REMOVED` actions dispatched for it.
     return tracks.filter(t => t.local && t.jitsiTrack);
 }
 
@@ -215,7 +215,7 @@ export function setTrackMuted(track, muted) {
 
     return track[f]().catch(error => {
 
-        // FIXME emit mute failed, so that the app can show error dialog
+        // FIXME Emit mute failed, so that the app can show error dialog.
         console.error(`set track ${f} failed`, error);
     });
 }

react/features/base/tracks/reducer.js

@@ -12,23 +12,24 @@ import {
 
 /**
  * @typedef {Object} Track
- * @property {(JitsiLocalTrack|JitsiRemoteTrack)} [jitsiTrack] - JitsiTrack
- * instance. Optional for local tracks if those are being created (GUM in
- * progress).
- * @property {boolean} local=false - If track is local.
- * @property {Promise} [gumProcess] - if local track is being created it
- * will have no JitsiTrack, but a 'gumProcess' set to a Promise with and extra
- * cancel().
- * @property {MEDIA_TYPE} mediaType=false - Media type of track.
+ * @property {(JitsiLocalTrack|JitsiRemoteTrack)} [jitsiTrack] - The associated
+ * {@code JitsiTrack} instance. Optional for local tracks if those are still
+ * being created (i.e. {@code getUserMedia} is still in progress).
+ * @property {Promise} [gumProcess] - If a local track is still being created,
+ * it will have no {@code JitsiTrack}, but a {@code gumProcess} set to a
+ * {@code Promise} with and extra {@code cancel()}.
+ * @property {boolean} local=false - If the track is local.
+ * @property {MEDIA_TYPE} mediaType=false - The media type of the track.
  * @property {boolean} mirror=false - The indicator which determines whether the
  * display/rendering of the track should be mirrored. It only makes sense in the
  * context of video (at least at the time of this writing).
- * @property {boolean} muted=false - If track is muted.
- * @property {(string|undefined)} participantId - ID of participant whom this
- * track belongs to.
- * @property {boolean} videoStarted=false - If video track has already started
- * to play.
- * @property {(VIDEO_TYPE|undefined)} videoType - Type of video track if any.
+ * @property {boolean} muted=false - If the track is muted.
+ * @property {(string|undefined)} participantId - The ID of the participant whom
+ * the track belongs to.
+ * @property {boolean} videoStarted=false - If the video track has already
+ * started to play.
+ * @property {(VIDEO_TYPE|undefined)} videoType - The type of video track if
+ * any.
  */
 
 /**

react/features/remote-video-menu/components/MuteRemoteParticipantDialog.web.js

@@ -95,9 +95,9 @@ class MuteRemoteParticipantDialog extends Component {
     /**
      * Renders the content of the dialog.
      *
-     * @returns {Component} the react component, which is the view of the dialog
-     * content
      * @private
+     * @returns {Component} The React {@code Component} which is the view of the
+     * dialog content.
      */
     _renderContent() {
         const { t } = this.props;