[RN] Fix documentation comments

* Javadoc introduced @code as a replacement of <code> and <tt> which is
  better aligned with other javadoc tags such as @link. Use it in the
  Java source code. If we switch to Kotlin, then we'll definitely use
  Markdown.

* There are more uses of @code in the JavaScript source code than <tt>
  so use @code for the sake of consistency. Eventually, I'd rather we
  switch to Markdown because it's easier on my eyes.

* Xcode is plain confused by @code and @link. The Internet says that
  Xcode supports the backquote character to denote the beginning and end
  of a string of characters which should be formatted for display as
  code but it doesn't work for me. <tt> is not rendered at all. So use
  the backquote which is rendered itself. Hopefully, if we switch to
  Markdown, then it'll be common between JavaScript and Objective-C
  source code.
This commit is contained in:
Lyubo Marinov
2017-10-01 01:35:19 -05:00
parent b3cef401f2
commit 4bf19d73fd
58 changed files with 333 additions and 417 deletions
+1 -1
View File
@@ -83,7 +83,7 @@ export function chooseBOSHAddress(config: Object, roomName: string) {
/* eslint-enable no-shadow */
/**
* Sends HTTP POST request to specified <tt>endpoint</tt>. In request the name
* Sends HTTP POST request to specified {@code endpoint}. In request the name
* of the room is included in JSON format:
* {
* "rooomName": "someroom12345"
+2 -2
View File
@@ -56,10 +56,10 @@ export function getURLWithoutParams(url: URL): URL {
* Converts a specific id to jid if it's not jid yet.
*
* @param {string} id - User id or jid.
* @param {Object} configHosts - The <tt>hosts</tt> part of the <tt>config</tt>
* @param {Object} configHosts - The {@code hosts} part of the {@code config}
* object.
* @returns {string} A string in the form of a JID (i.e.
* <tt>user@server.com</tt>).
* {@code user@server.com}).
*/
export function toJid(id: string, { authdomain, domain }: Object): string {
return id.indexOf('@') >= 0 ? id : `${id}@${authdomain || domain}`;
+8 -8
View File
@@ -6,10 +6,10 @@ import { isDialogOpen } from './functions';
/**
* Signals Dialog to close its dialog.
*
* @param {Object} [component] - The <tt>Dialog</tt> component to close/hide. If
* <tt>undefined</tt>, closes/hides <tt>Dialog</tt> regardless of which
* component it's rendering; otherwise, closes/hides <tt>Dialog</tt> only if
* it's rendering the specified <tt>component</tt>.
* @param {Object} [component] - The {@code Dialog} component to close/hide. If
* {@code undefined}, closes/hides {@code Dialog} regardless of which
* component it's rendering; otherwise, closes/hides {@code Dialog} only if
* it's rendering the specified {@code component}.
* @returns {{
* type: HIDE_DIALOG,
* component: (React.Component | undefined)
@@ -26,8 +26,8 @@ export function hideDialog(component: ?Object) {
* Signals Dialog to open dialog.
*
* @param {Object} component - The component to display as dialog.
* @param {Object} [componentProps] - The React <tt>Component</tt> props of the
* specified <tt>component</tt>.
* @param {Object} [componentProps] - The React {@code Component} props of the
* specified {@code component}.
* @returns {{
* type: OPEN_DIALOG,
* component: React.Component,
@@ -48,8 +48,8 @@ export function openDialog(component: Object, componentProps: ?Object) {
* dialog.
*
* @param {Object} component - The component to display as dialog.
* @param {Object} [componentProps] - The React <tt>Component</tt> props of the
* specified <tt>component</tt>.
* @param {Object} [componentProps] - The React {@code Component} props of the
* specified {@code component}.
* @returns {Function}
*/
export function toggleDialog(component: Object, componentProps: ?Object) {
@@ -9,7 +9,7 @@ import { DIALOG_PROP_TYPES } from '../constants';
*/
export default class AbstractDialog extends Component {
/**
* <tt>AbstractDialog</tt> React <tt>Component</tt>'s prop types.
* {@code AbstractDialog} React {@code Component}'s prop types.
*
* @static
*/
@@ -17,7 +17,7 @@ export default class AbstractDialog extends Component {
...DIALOG_PROP_TYPES,
/**
* The React <tt>Component</tt> children of <tt>AbstractDialog</tt>
* The React {@code Component} children of {@code AbstractDialog}
* which represents the dialog's body.
*/
children: PropTypes.node,
@@ -29,9 +29,9 @@ export default class AbstractDialog extends Component {
};
/**
* Initializes a new <tt>AbstractDialog</tt> instance.
* Initializes a new {@code AbstractDialog} instance.
*
* @param {Object} props - The read-only React <tt>Component</tt> props with
* @param {Object} props - The read-only React {@code Component} props with
* which the new instance is to be initialized.
*/
constructor(props) {
@@ -82,10 +82,10 @@ export default class AbstractDialog extends Component {
}
/**
* Submits this dialog. If the React <tt>Component</tt> prop
* <tt>onSubmit</tt> is defined, the function that is the value of the prop
* is invoked. If the function returns a <tt>thenable</tt>, then the
* resolution of the <tt>thenable</tt> is awaited. If the submission
* Submits this dialog. If the React {@code Component} prop
* {@code onSubmit} is defined, the function that is the value of the prop
* is invoked. If the function returns a {@code thenable}, then the
* resolution of the {@code thenable} is awaited. If the submission
* completes successfully, a redux action will be dispatched to hide this
* dialog.
*
@@ -126,7 +126,7 @@ export default class AbstractDialog extends Component {
}
/**
* Notifies this <tt>AbstractDialog</tt> that it has been submitted
* Notifies this {@code AbstractDialog} that it has been submitted
* successfully. Dispatches a redux action to hide this dialog after it has
* been submitted.
*
@@ -140,7 +140,7 @@ export default class AbstractDialog extends Component {
}
/**
* Notifies this <tt>AbstractDialog</tt> that its submission has failed.
* Notifies this {@code AbstractDialog} that its submission has failed.
*
* @private
* @returns {void}
@@ -13,14 +13,14 @@ import styles from './styles';
/**
* The value of the style property {@link _TAG_KEY} which identifies the
* OK/submit button of <tt>Prompt</tt>.
* OK/submit button of {@code Prompt}.
*/
const _SUBMIT_TEXT_TAG_VALUE = '_SUBMIT_TEXT_TAG_VALUE';
/**
* The name of the style property which identifies ancestors of <tt>Prompt</tt>
* The name of the style property which identifies ancestors of {@code Prompt}
* such as its OK/submit button for the purposes of workarounds implemented by
* <tt>Dialog</tt>.
* {@code Dialog}.
*
* XXX The value may trigger a react-native warning in the Debug configuration
* but, unfortunately, I couldn't find a value that wouldn't.
@@ -28,11 +28,11 @@ const _SUBMIT_TEXT_TAG_VALUE = '_SUBMIT_TEXT_TAG_VALUE';
const _TAG_KEY = '_TAG_KEY';
/**
* Implements <tt>AbstractDialog</tt> on react-native using <tt>Prompt</tt>.
* Implements {@code AbstractDialog} on react-native using {@code Prompt}.
*/
class Dialog extends AbstractDialog {
/**
* <tt>AbstractDialog</tt>'s React <tt>Component</tt> prop types.
* {@code AbstractDialog}'s React {@code Component} prop types.
*
* @static
*/
@@ -164,14 +164,14 @@ class Dialog extends AbstractDialog {
}
/**
* Creates a deep clone of a specific <tt>ReactElement</tt> with the results
* Creates a deep clone of a specific {@code ReactElement} with the results
* of calling a specific function on every node of a specific
* <tt>ReactElement</tt> tree.
* {@code ReactElement} tree.
*
* @param {ReactElement} element - The <tt>ReactElement</tt> to clone and
* call the specified <tt>f</tt> on.
* @param {ReactElement} element - The {@code ReactElement} to clone and
* call the specified {@code f} on.
* @param {Function} f - The function to call on every node of the
* <tt>ReactElement</tt> tree represented by the specified <tt>element</tt>.
* {@code ReactElement} tree represented by the specified {@code element}.
* @private
* @returns {ReactElement}
*/
@@ -42,7 +42,7 @@ export class DialogContainer extends Component {
}
/**
* Maps (parts of) the redux state to the associated <tt>DialogContainer</tt>'s
* Maps (parts of) the redux state to the associated {@code DialogContainer}'s
* props.
*
* @param {Object} state - The redux state.
@@ -1,18 +1,18 @@
import { ColorPalette, createStyleSheet } from '../../styles';
/**
* The React <tt>Component</tt> styles of the feature base/dialog.
* The React {@code Component} styles of the feature base/dialog.
*/
export default createStyleSheet({
/**
* The style of the <tt>Text</tt> in a <tt>Dialog</tt> button.
* The style of the {@code Text} in a {@code Dialog} button.
*/
buttonText: {
color: ColorPalette.blue
},
/**
* The style of the <tt>Text</tt> in a <tt>Dialog</tt> button which is
* The style of the {@code Text} in a {@code Dialog} button which is
* disabled.
*/
disabledButtonText: {
+4 -4
View File
@@ -3,13 +3,13 @@
import { toState } from '../redux';
/**
* Checks if a <tt>Dialog</tt> with a specific <tt>component</tt> is currently
* Checks if a {@code Dialog} with a specific {@code component} is currently
* open.
*
* @param {Function|Object} stateful - The redux store, the redux
* <tt>getState</tt> function, or the redux state itself.
* @param {React.Component} component - The <tt>component</tt> of a
* <tt>Dialog</tt> to be checked.
* {@code getState} function, or the redux state itself.
* @param {React.Component} component - The {@code component} of a
* {@code Dialog} to be checked.
* @returns {boolean}
*/
export function isDialogOpen(stateful: Function | Object, component: Object) {
@@ -114,7 +114,7 @@ function _LOGE(...args) {
/**
* Adapts react-native-webrtc's {@link RTCPeerConnection#setRemoteDescription}
* implementation which uses the deprecated, callback-based version to the
* <tt>Promise</tt>-based version.
* {@code Promise}-based version.
*
* @param {RTCSessionDescription} sessionDescription - The RTCSessionDescription
* which specifies the configuration of the remote end of the connection.
@@ -2,27 +2,27 @@ import { AsyncStorage } from 'react-native';
/**
* A Web Sorage API implementation used for polyfilling
* <tt>window.localStorage</tt> and/or <tt>window.sessionStorage</tt>.
* {@code window.localStorage} and/or {@code window.sessionStorage}.
* <p>
* The Web Storage API is synchronous whereas React Native's builtin generic
* storage API <tt>AsyncStorage</tt> is asynchronous so the implementation with
* storage API {@code AsyncStorage} is asynchronous so the implementation with
* persistence is optimistic: it will first store the value locally in memory so
* that results can be served synchronously and then persist the value
* asynchronously. If an asynchronous operation produces an error, it's ignored.
*/
export default class Storage {
/**
* Initializes a new <tt>Storage</tt> instance. Loads all previously
* persisted data items from React Native's <tt>AsyncStorage</tt> if
* Initializes a new {@code Storage} instance. Loads all previously
* persisted data items from React Native's {@code AsyncStorage} if
* necessary.
*
* @param {string|undefined} keyPrefix - The prefix of the
* <tt>AsyncStorage</tt> keys to be persisted by this storage.
* {@code AsyncStorage} keys to be persisted by this storage.
*/
constructor(keyPrefix) {
/**
* The prefix of the <tt>AsyncStorage</tt> keys persisted by this
* storage. If <tt>undefined</tt>, then the data items stored in this
* The prefix of the {@code AsyncStorage} keys persisted by this
* storage. If {@code undefined}, then the data items stored in this
* storage will not be persisted.
*
* @private
@@ -81,8 +81,8 @@ export default class Storage {
* Returns the value associated with a specific key in this storage.
*
* @param {string} key - The name of the key to retrieve the value of.
* @returns {string|null} The value associated with <tt>key</tt> or
* <tt>null</tt>.
* @returns {string|null} The value associated with {@code key} or
* {@code null}.
*/
getItem(key) {
return this.hasOwnProperty(key) ? this[key] : null;
@@ -128,7 +128,7 @@ export default class Storage {
* value. If the key exists already, updates its value.
*
* @param {string} key - The name of the key to add/update.
* @param {string} value - The value to associate with <tt>key</tt>.
* @param {string} value - The value to associate with {@code key}.
* @returns {void}
*/
setItem(key, value) {
+3 -3
View File
@@ -18,14 +18,14 @@ export function isVideoMutedByAudioOnly(stateful: Function | Object) {
/**
* Determines whether video is currently muted by a specific
* <tt>VIDEO_MUTISM_AUTHORITY</tt>.
* {@code VIDEO_MUTISM_AUTHORITY}.
*
* @param {Function|Object} stateful - The redux store, state, or
* {@code getState} function.
* @param {number} videoMutismAuthority - The <tt>VIDEO_MUTISM_AUTHORITY</tt>
* @param {number} videoMutismAuthority - The {@code VIDEO_MUTISM_AUTHORITY}
* which is to be checked whether it has muted video.
* @returns {boolean} If video is currently muted by the specified
* <tt>videoMutismAuthority</tt>, then <tt>true</tt>; otherwise, <tt>false</tt>.
* {@code videoMutismAuthority}, then {@code true}; otherwise, {@code false}.
*/
function _isVideoMutedByAuthority(
stateful: Function | Object,
@@ -11,9 +11,9 @@ import { ColorPalette } from '../../styles';
* specified one fails to load.
*
* XXX The relative path to the default/stock (image) file is defined by the
* <tt>const</tt> <tt>DEFAULT_AVATAR_RELATIVE_PATH</tt>. Unfortunately, the
* {@code const} {@code DEFAULT_AVATAR_RELATIVE_PATH}. Unfortunately, the
* packager of React Native cannot deal with it early enough for the following
* <tt>require</tt> to succeed at runtime. Anyway, be sure to synchronize the
* {@code require} to succeed at runtime. Anyway, be sure to synchronize the
* relative path on Web and mobile for the purposes of consistency.
*
* @private
@@ -146,9 +146,9 @@ export default class Avatar extends Component {
}
/**
* Notifies this <tt>Component</tt> that it will be unmounted and destroyed
* Notifies this {@code Component} that it will be unmounted and destroyed
* and, most importantly, that it should no longer call
* {@link #setState(Object)}. <tt>Avatar</tt> needs it because it downloads
* {@link #setState(Object)}. {@code Avatar} needs it because it downloads
* images via {@link ImageCache} which will asynchronously notify about
* success.
*
@@ -163,7 +163,7 @@ export default class Avatar extends Component {
* Computes a hash over the URI and returns a HSL background color. We use
* 75% as lightness, for nice pastel style colors.
*
* @param {Object} props - The read-only React <tt>Component</tt> props from
* @param {Object} props - The read-only React {@code Component} props from
* which the background color is to be generated.
* @private
* @returns {string} - The HSL CSS property.
@@ -5,7 +5,7 @@
* XXX (1) Web/React utilizes relativity on the Jitsi Meet deployment.
* (2) Mobile/React Native utilizes relativity on the local file system at build
* time. Unfortunately, the packager of React Native cannot deal with the
* <tt>const</tt> early enough for <tt>require</tt> to succeed at runtime.
* {@code const} early enough for {@code require} to succeed at runtime.
* Anyway, be sure to synchronize the relative path on Web and mobile for the
* purposes of consistency.
*
+2 -2
View File
@@ -25,8 +25,8 @@ import {
* @property {boolean} pinned - If true, participant is currently a
* "PINNED_ENDPOINT".
* @property {boolean} dominantSpeaker - If this participant is the dominant
* speaker in the (associated) conference, <tt>true</tt>; otherwise,
* <tt>false</tt>.
* speaker in the (associated) conference, {@code true}; otherwise,
* {@code false}.
* @property {string} email - Participant email.
*/
@@ -8,7 +8,7 @@ import { translate } from '../../../i18n';
declare var interfaceConfig: Object;
/**
* The CSS style of the element with CSS class <tt>rightwatermark</tt>.
* The CSS style of the element with CSS class {@code rightwatermark}.
*
* @private
*/
+27 -27
View File
@@ -40,19 +40,19 @@ export function equals(a: any, b: any) {
/**
* Sets a specific property of a specific state to a specific value. Prevents
* unnecessary state changes (when the specified <tt>value</tt> is equal to the
* value of the specified <tt>property</tt> of the specified <tt>state</tt>).
* unnecessary state changes (when the specified {@code value} is equal to the
* value of the specified {@code property} of the specified {@code state}).
*
* @param {Object} state - The (Redux) state from which a new state is to be
* constructed by setting the specified <tt>property</tt> to the specified
* <tt>value</tt>.
* @param {string} property - The property of <tt>state</tt> which is to be
* assigned the specified <tt>value</tt> (in the new state).
* @param {*} value - The value to assign to the specified <tt>property</tt>.
* @returns {Object} The specified <tt>state</tt> if the value of the specified
* <tt>property</tt> equals the specified <tt>value/tt>; otherwise, a new state
* constructed from the specified <tt>state</tt> by setting the specified
* <tt>property</tt> to the specified <tt>value</tt>.
* constructed by setting the specified {@code property} to the specified
* {@code value}.
* @param {string} property - The property of {@code state} which is to be
* assigned the specified {@code value} (in the new state).
* @param {*} value - The value to assign to the specified {@code property}.
* @returns {Object} The specified {@code state} if the value of the specified
* {@code property} equals the specified <tt>value/tt>; otherwise, a new state
* constructed from the specified {@code state} by setting the specified
* {@code property} to the specified {@code value}.
*/
export function set(state: Object, property: string, value: any) {
return _set(state, property, value, /* copyOnWrite */ true);
@@ -62,22 +62,22 @@ export function set(state: Object, property: string, value: any) {
/**
* Sets a specific property of a specific state to a specific value. Prevents
* unnecessary state changes (when the specified <tt>value</tt> is equal to the
* value of the specified <tt>property</tt> of the specified <tt>state</tt>).
* unnecessary state changes (when the specified {@code value} is equal to the
* value of the specified {@code property} of the specified {@code state}).
*
* @param {Object} state - The (Redux) state from which a state is to be
* constructed by setting the specified <tt>property</tt> to the specified
* <tt>value</tt>.
* @param {string} property - The property of <tt>state</tt> which is to be
* assigned the specified <tt>value</tt>.
* @param {*} value - The value to assign to the specified <tt>property</tt>.
* @param {boolean} copyOnWrite - If the specified <tt>state</tt> is to not be
* modified, <tt>true</tt>; otherwise, <tt>false</tt>.
* @returns {Object} The specified <tt>state</tt> if the value of the specified
* <tt>property</tt> equals the specified <tt>value/tt> or <tt>copyOnWrite</tt>
* constructed by setting the specified {@code property} to the specified
* {@code value}.
* @param {string} property - The property of {@code state} which is to be
* assigned the specified {@code value}.
* @param {*} value - The value to assign to the specified {@code property}.
* @param {boolean} copyOnWrite - If the specified {@code state} is to not be
* modified, {@code true}; otherwise, {@code false}.
* @returns {Object} The specified {@code state} if the value of the specified
* {@code property} equals the specified <tt>value/tt> or {@code copyOnWrite}
* is truthy; otherwise, a new state constructed from the specified
* <tt>state</tt> by setting the specified <tt>property</tt> to the specified
* <tt>value</tt>.
* {@code state} by setting the specified {@code property} to the specified
* {@code value}.
*/
function _set(
state: Object,
@@ -112,12 +112,12 @@ function _set(
/* eslint-enable max-params */
/**
* Returns redux state from the specified <tt>stateful</tt> which is presumed to
* Returns redux state from the specified {@code stateful} which is presumed to
* be related to the redux state (e.g. the redux store, the redux
* <tt>getState</tt> function).
* {@code getState} function).
*
* @param {Function|Object} stateful - The entity such as the redux store or the
* redux <tt>getState</tt> function from which the redux state is to be
* redux {@code getState} function from which the redux state is to be
* returned.
* @returns {Object} The redux state.
*/
+11 -11
View File
@@ -329,16 +329,16 @@ export function _disposeAndRemoveTracks(tracks) {
}
/**
* Finds the first <tt>JitsiLocalTrack</tt> in a specific array/list of
* <tt>JitsiTrack</tt>s which is of a specific <tt>MEDIA_TYPE</tt>.
* Finds the first {@code JitsiLocalTrack} in a specific array/list of
* {@code JitsiTrack}s which is of a specific {@code MEDIA_TYPE}.
*
* @param {JitsiTrack[]} tracks - The array/list of <tt>JitsiTrack</tt>s to look
* @param {JitsiTrack[]} tracks - The array/list of {@code JitsiTrack}s to look
* through.
* @param {MEDIA_TYPE} mediaType - The <tt>MEDIA_TYPE</tt> of the first
* <tt>JitsiLocalTrack</tt> to be returned.
* @param {MEDIA_TYPE} mediaType - The {@code MEDIA_TYPE} of the first
* {@code JitsiLocalTrack} to be returned.
* @private
* @returns {JitsiLocalTrack} The first <tt>JitsiLocalTrack</tt>, if any, in the
* specified <tt>tracks</tt> of the specified <tt>mediaType</tt>.
* @returns {JitsiLocalTrack} The first {@code JitsiLocalTrack}, if any, in the
* specified {@code tracks} of the specified {@code mediaType}.
*/
function _getLocalTrack(tracks, mediaType) {
return tracks.find(track =>
@@ -384,11 +384,11 @@ function _getLocalTracksToChange(currentTracks, newTracks) {
}
/**
* Implements the <tt>Promise</tt> rejection handler of
* <tt>createLocalTracksA</tt> and <tt>createLocalTracksF</tt>.
* Implements the {@code Promise} rejection handler of
* {@code createLocalTracksA} and {@code createLocalTracksF}.
*
* @param {Object} reason - The <tt>Promise</tt> rejection reason.
* @param {string} device - The device/<tt>MEDIA_TYPE</tt> associated with the
* @param {Object} reason - The {@code Promise} rejection reason.
* @param {string} device - The device/{@code MEDIA_TYPE} associated with the
* rejection.
* @private
* @returns {Function}
+6 -6
View File
@@ -172,14 +172,14 @@ export function isLocalTrackMuted(tracks, mediaType) {
}
/**
* Mutes or unmutes a specific <tt>JitsiLocalTrack</tt>. If the muted state of
* the specified <tt>track</tt> is already in accord with the specified
* <tt>muted</tt> value, then does nothing.
* Mutes or unmutes a specific {@code JitsiLocalTrack}. If the muted state of
* the specified {@code track} is already in accord with the specified
* {@code muted} value, then does nothing.
*
* @param {JitsiLocalTrack} track - The <tt>JitsiLocalTrack</tt> to mute or
* @param {JitsiLocalTrack} track - The {@code JitsiLocalTrack} to mute or
* unmute.
* @param {boolean} muted - If the specified <tt>track</tt> is to be muted, then
* <tt>true</tt>; otherwise, <tt>false</tt>.
* @param {boolean} muted - If the specified {@code track} is to be muted, then
* {@code true}; otherwise, {@code false}.
* @returns {Promise}
*/
export function setTrackMuted(track, muted) {
+6 -6
View File
@@ -128,16 +128,16 @@ MiddlewareRegistry.register(store => next => action => {
});
/**
* Gets the local track associated with a specific <tt>MEDIA_TYPE</tt> in a
* Gets the local track associated with a specific {@code MEDIA_TYPE} in a
* specific redux store.
*
* @param {Store} store - The redux store from which the local track associated
* with the specified <tt>mediaType</tt> is to be retrieved.
* @param {MEDIA_TYPE} mediaType - The <tt>MEDIA_TYPE</tt> of the local track to
* be retrieved from the specified <tt>store</tt>.
* with the specified {@code mediaType} is to be retrieved.
* @param {MEDIA_TYPE} mediaType - The {@code MEDIA_TYPE} of the local track to
* be retrieved from the specified {@code store}.
* @private
* @returns {Track} The local <tt>Track</tt> associated with the specified
* <tt>mediaType</tt> in the specified <tt>store</tt>.
* @returns {Track} The local {@code Track} associated with the specified
* {@code mediaType} in the specified {@code store}.
*/
function _getLocalTrack({ getState }, mediaType: MEDIA_TYPE) {
return getLocalTrack(getState()['features/base/tracks'], mediaType);
@@ -1,7 +1,7 @@
/**
* Loads a script from a specific URL. React Native cannot load a JS
* file/resource/URL via a <script> HTML element, so the implementation
* fetches the specified <tt>url</tt> as plain text using {@link fetch()} and
* fetches the specified {@code url} as plain text using {@link fetch()} and
* then evaluates the fetched string as JavaScript code (using {@link eval()}).
*
* @param {string} url - The absolute URL from which the script is to be