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/api.ts

@@ -66,8 +66,7 @@ export interface IRecoveryKey {
 export interface ICreateSecretStorageOpts {
     /**
      * Function called to await a secret storage key creation flow.
-     * Returns:
-     *     {Promise<Object>} Object with public key metadata, encoded private
+     * @returns Promise resolving to an object with public key metadata, encoded private
      *     recovery key which should be disposed of after displaying to the user,
      *     and raw private key to avoid round tripping if needed.
      */
@@ -131,6 +130,7 @@ export interface IImportOpts {
 }
 
 export interface IImportRoomKeysOpts {
+    /** called with an object that has a "stage" param */
     progressCallback?: (stage: IImportOpts) => void;
     untrusted?: boolean;
     source?: string; // TODO: Enum