Improve tsdoc types (#2940)

* Install eslint-plugin-jsdoc

* Enable lint rule jsdoc/no-types

* Make tsdoc more valid, add required hyphens and s/return/returns/g

* Stash tsdoc work

* Fix mistypes

* Stash

* Stash

* More tsdoc work

* Remove useless doc params

* Fixup docs

* Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Update src/crypto/verification/request/ToDeviceChannel.ts

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Update src/client.ts

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Update src/client.ts

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Update src/client.ts

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Iterate

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

src/crypto/backup.ts

@@ -15,8 +15,6 @@ limitations under the License.
 */
 
 /**
- * @module crypto/backup
- *
  * Classes for dealing with key backup.
  */
 
@@ -134,7 +132,7 @@ export class BackupManager {
      *
      * Throws an error if a problem is detected.
      *
-     * @param {IKeyBackupInfo} info the key backup info
+     * @param info - the key backup info
      */
     public static checkBackupVersion(info: IKeyBackupInfo): void {
         const Algorithm = algorithmsByName[info.algorithm];
@@ -276,7 +274,7 @@ export class BackupManager {
      * Forces a re-check of the key backup and enables/disables it
      * as appropriate.
      *
-     * @return {Object} Object with backup info (as returned by
+     * @returns Object with backup info (as returned by
      *     getKeyBackupVersion) in backupInfo and
      *     trust information (as returned by isKeyBackupTrusted)
      *     in trustInfo.
@@ -309,15 +307,7 @@ export class BackupManager {
     /**
      * Check if the given backup info is trusted.
      *
-     * @param {IKeyBackupInfo} backupInfo key backup info dict from /room_keys/version
-     * @return {object} {
-     *     usable: [bool], // is the backup trusted, true iff there is a sig that is valid & from a trusted device
-     *     sigs: [
-     *         valid: [bool || null], // true: valid, false: invalid, null: cannot attempt validation
-     *         deviceId: [string],
-     *         device: [DeviceInfo || null],
-     *     ]
-     * }
+     * @param backupInfo - key backup info dict from /room_keys/version
      */
     public async isKeyBackupTrusted(backupInfo?: IKeyBackupInfo): Promise<TrustInfo> {
         const ret = {
@@ -432,7 +422,7 @@ export class BackupManager {
      * Schedules sending all keys waiting to be sent to the backup, if not already
      * scheduled. Retries if necessary.
      *
-     * @param maxDelay Maximum delay to wait in ms. 0 means no delay.
+     * @param maxDelay - Maximum delay to wait in ms. 0 means no delay.
      */
     public async scheduleKeyBackupSend(maxDelay = 10000): Promise<void> {
         if (this.sendingBackups) return;
@@ -490,8 +480,8 @@ export class BackupManager {
      * Take some e2e keys waiting to be backed up and send them
      * to the backup.
      *
-     * @param {number} limit Maximum number of keys to back up
-     * @returns {number} Number of sessions backed up
+     * @param limit - Maximum number of keys to back up
+     * @returns Number of sessions backed up
      */
     public async backupPendingKeys(limit: number): Promise<number> {
         const sessions = await this.baseApis.crypto!.cryptoStore.getSessionsNeedingBackup(limit);
@@ -573,7 +563,7 @@ export class BackupManager {
     /**
      * Marks all group sessions as needing to be backed up without scheduling
      * them to upload in the background.
-     * @returns {Promise<int>} Resolves to the number of sessions now requiring a backup
+     * @returns Promise which resolves to the number of sessions now requiring a backup
      *     (which will be equal to the number of sessions in the store).
      */
     public async flagAllGroupSessionsForBackup(): Promise<number> {
@@ -599,7 +589,7 @@ export class BackupManager {
 
     /**
      * Counts the number of end to end session keys that are waiting to be backed up
-     * @returns {Promise<int>} Resolves to the number of sessions requiring backup
+     * @returns Promise which resolves to the number of sessions requiring backup
      */
     public countSessionsNeedingBackup(): Promise<number> {
         return this.baseApis.crypto!.cryptoStore.countSessionsNeedingBackup();