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.
This commit is contained in:
Lyubo Marinov
parent
f37a12c332
commit
decf9c4991
|
|
@ -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) {
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
* Cancels and waits for any {@code getUserMedia} process/currently in progress
|
||||
* to complete/settle.
|
||||
*
|
||||
* @param {MEDIA_TYPE} mediaType - The type of the media for which the track was
|
||||
* being created.
|
||||
* @returns {{
|
||||
* type,
|
||||
* trackType: MEDIA_TYPE
|
||||
* }}
|
||||
* @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 _trackCreateCanceled(mediaType) {
|
||||
return {
|
||||
type: TRACK_CREATE_CANCELED,
|
||||
trackType: mediaType
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Cancels and waits for any get user media operations currently in progress to
|
||||
* complete.
|
||||
*
|
||||
* @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).
|
||||
* @private
|
||||
*/
|
||||
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
|
||||
};
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
});
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
*/
|
||||
|
||||
/**
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
Loading…
Reference in New Issue