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>

spec/TestClient.ts

@@ -105,7 +105,7 @@ export class TestClient {
 
     /**
      * stop the client
-     * @return {Promise} Resolves once the mock http backend has finished all pending flushes
+     * @returns Promise which resolves once the mock http backend has finished all pending flushes
      */
     public async stop(): Promise<void> {
         this.client.stopClient();
@@ -135,7 +135,7 @@ export class TestClient {
      * set up an expectation that the keys will be uploaded, and wait for
      * that to happen.
      *
-     * @returns {Promise} for the one-time keys
+     * @returns Promise for the one-time keys
      */
     public awaitOneTimeKeyUpload(): Promise<Record<string, IOneTimeKey>> {
         if (Object.keys(this.oneTimeKeys!).length != 0) {
@@ -177,7 +177,7 @@ export class TestClient {
      *
      * We check that the query contains each of the users in `response`.
      *
-     * @param {Object} response   response to the query.
+     * @param response -   response to the query.
      */
     public expectKeyQuery(response: IDownloadKeyResult) {
         this.httpBackend.when('POST', '/keys/query').respond<IDownloadKeyResult>(
@@ -202,7 +202,7 @@ export class TestClient {
     /**
      * get the uploaded curve25519 device key
      *
-     * @return {string} base64 device key
+     * @returns base64 device key
      */
     public getDeviceKey(): string {
         const keyId = 'curve25519:' + this.deviceId;
@@ -212,7 +212,7 @@ export class TestClient {
     /**
      * get the uploaded ed25519 device key
      *
-     * @return {string} base64 device key
+     * @returns base64 device key
      */
     public getSigningKey(): string {
         const keyId = 'ed25519:' + this.deviceId;

spec/integ/devicelist-integ.spec.ts

@@ -26,9 +26,7 @@ const ROOM_ID = "!room:id";
  * get a /sync response which contains a single e2e room (ROOM_ID), with the
  * members given
  *
- * @param {string[]} roomMembers
- *
- * @return {object} sync response
+ * @returns sync response
  */
 function getSyncResponse(roomMembers: string[]) {
     const stateEvents = [

spec/integ/matrix-client-crypto.spec.ts

@@ -60,7 +60,7 @@ async function bobUploadsDeviceKeys(): Promise<void> {
 /**
  * Set an expectation that querier will query uploader's keys; then flush the http request.
  *
- * @return {promise} resolves once the http request has completed.
+ * @returns resolves once the http request has completed.
  */
 function expectQueryKeys(querier: TestClient, uploader: TestClient): Promise<number> {
     // can't query keys before bob has uploaded them
@@ -83,7 +83,7 @@ const expectBobQueryKeys = () => expectQueryKeys(bobTestClient, aliTestClient);
 /**
  * Set an expectation that ali will claim one of bob's keys; then flush the http request.
  *
- * @return {promise} resolves once the http request has completed.
+ * @returns resolves once the http request has completed.
  */
 async function expectAliClaimKeys(): Promise<void> {
     const keys = await bobTestClient.awaitOneTimeKeyUpload();
@@ -151,7 +151,7 @@ const bobEnablesEncryption = () => clientEnablesEncryption(bobTestClient.client)
  * Ali sends a message, first claiming e2e keys. Set the expectations and
  * check the results.
  *
- * @return {promise} which resolves to the ciphertext for Bob's device.
+ * @returns which resolves to the ciphertext for Bob's device.
  */
 async function aliSendsFirstMessage(): Promise<OlmPayload> {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -168,7 +168,7 @@ async function aliSendsFirstMessage(): Promise<OlmPayload> {
  * Ali sends a message without first claiming e2e keys. Set the expectations
  * and check the results.
  *
- * @return {promise} which resolves to the ciphertext for Bob's device.
+ * @returns which resolves to the ciphertext for Bob's device.
  */
 async function aliSendsMessage(): Promise<OlmPayload> {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -183,7 +183,7 @@ async function aliSendsMessage(): Promise<OlmPayload> {
  * Bob sends a message, first querying (but not claiming) e2e keys. Set the
  * expectations and check the results.
  *
- * @return {promise} which resolves to the ciphertext for Ali's device.
+ * @returns which resolves to the ciphertext for Ali's device.
  */
 async function bobSendsReplyMessage(): Promise<OlmPayload> {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -198,7 +198,7 @@ async function bobSendsReplyMessage(): Promise<OlmPayload> {
 /**
  * Set an expectation that Ali will send a message, and flush the request
  *
- * @return {promise} which resolves to the ciphertext for Bob's device.
+ * @returns which resolves to the ciphertext for Bob's device.
  */
 async function expectAliSendMessageRequest(): Promise<OlmPayload> {
     const content = await expectSendMessageRequest(aliTestClient.httpBackend);
@@ -212,7 +212,7 @@ async function expectAliSendMessageRequest(): Promise<OlmPayload> {
 /**
  * Set an expectation that Bob will send a message, and flush the request
  *
- * @return {promise} which resolves to the ciphertext for Bob's device.
+ * @returns which resolves to the ciphertext for Bob's device.
  */
 async function expectBobSendMessageRequest(): Promise<OlmPayload> {
     const content = await expectSendMessageRequest(bobTestClient.httpBackend);
@@ -321,8 +321,7 @@ async function recvMessage(
  * Send an initial sync response to the client (which just includes the member
  * list for our test room).
  *
- * @param {TestClient} testClient
- * @returns {Promise} which resolves when the sync has been flushed.
+ * @returns which resolves when the sync has been flushed.
  */
 function firstSync(testClient: TestClient): Promise<void> {
     // send a sync response including our test room.

spec/integ/matrix-client-syncing.spec.ts

@@ -1658,8 +1658,8 @@ describe("MatrixClient syncing", () => {
     /**
      * waits for the MatrixClient to emit one or more 'sync' events.
      *
-     * @param {Number?} numSyncs number of syncs to wait for
-     * @returns {Promise} promise which resolves after the sync events have happened
+     * @param numSyncs - number of syncs to wait for
+     * @returns promise which resolves after the sync events have happened
      */
     function awaitSyncEvent(numSyncs?: number) {
         return utils.syncPromise(client!, numSyncs);

spec/integ/megolm-integ.spec.ts

@@ -220,8 +220,8 @@ describe("megolm", () => {
      * Get the device keys for testOlmAccount in a format suitable for a
      * response to /keys/query
      *
-     * @param {string} userId The user ID to query for
-     * @returns {IDownloadKeyResult} The fake query response
+     * @param userId - The user ID to query for
+     * @returns The fake query response
      */
     function getTestKeysQueryResponse(userId: string): IDownloadKeyResult {
         const testE2eKeys = JSON.parse(testOlmAccount.identity_keys());
@@ -248,8 +248,8 @@ describe("megolm", () => {
      * Get a one-time key for testOlmAccount in a format suitable for a
      * response to /keys/claim
 
-     * @param {string} userId The user ID to query for
-     * @returns {IClaimOTKsResult} The fake key claim response
+     * @param userId - The user ID to query for
+     * @returns The fake key claim response
      */
     function getTestKeysClaimResponse(userId: string): IClaimOTKsResult {
         testOlmAccount.generate_one_time_keys(1);

spec/integ/sliding-sync.spec.ts

@@ -1446,11 +1446,11 @@ function timeout(delayMs: number, reason: string): { promise: Promise<never>, ca
 
 /**
  * Listen until a callback returns data.
- * @param {EventEmitter} emitter The event emitter
- * @param {string} eventName The event to listen for
- * @param {function} callback The callback which will be invoked when events fire. Return something truthy from this to resolve the promise.
- * @param {number} timeoutMs The number of milliseconds to wait for the callback to return data. Default: 500ms.
- * @returns {Promise} A promise which will be resolved when the callback returns data. If the callback throws or the timeout is reached,
+ * @param emitter - The event emitter
+ * @param eventName - The event to listen for
+ * @param callback - The callback which will be invoked when events fire. Return something truthy from this to resolve the promise.
+ * @param timeoutMs - The number of milliseconds to wait for the callback to return data. Default: 500ms.
+ * @returns A promise which will be resolved when the callback returns data. If the callback throws or the timeout is reached,
  * the promise is rejected.
  */
 function listenUntil<T>(

spec/test-utils/test-utils.ts

@@ -13,9 +13,9 @@ import { eventMapperFor } from "../../src/event-mapper";
 /**
  * Return a promise that is resolved when the client next emits a
  * SYNCING event.
- * @param {Object} client The client
- * @param {Number=} count Number of syncs to wait for (default 1)
- * @return {Promise} Resolves once the client has emitted a SYNCING event
+ * @param client - The client
+ * @param count - Number of syncs to wait for (default 1)
+ * @returns Promise which resolves once the client has emitted a SYNCING event
  */
 export function syncPromise(client: MatrixClient, count = 1): Promise<void> {
     if (count <= 0) {
@@ -41,9 +41,9 @@ export function syncPromise(client: MatrixClient, count = 1): Promise<void> {
 
 /**
  * Create a spy for an object and automatically spy its methods.
- * @param {*} constr The class constructor (used with 'new')
- * @param {string} name The name of the class
- * @return {Object} An instantiated object with spied methods/properties.
+ * @param constr - The class constructor (used with 'new')
+ * @param name - The name of the class
+ * @returns An instantiated object with spied methods/properties.
  */
 export function mock<T>(constr: { new(...args: any[]): T }, name: string): T {
     // Based on http://eclipsesource.com/blogs/2014/03/27/mocks-in-jasmine-tests/
@@ -84,15 +84,15 @@ interface IEventOpts {
 let testEventIndex = 1; // counter for events, easier for comparison of randomly generated events
 /**
  * Create an Event.
- * @param {Object} opts Values for the event.
- * @param {string} opts.type The event.type
- * @param {string} opts.room The event.room_id
- * @param {string} opts.sender The event.sender
- * @param {string} opts.skey Optional. The state key (auto inserts empty string)
- * @param {Object} opts.content The event.content
- * @param {boolean} opts.event True to make a MatrixEvent.
- * @param {MatrixClient} client If passed along with opts.event=true will be used to set up re-emitters.
- * @return {Object} a JSON object representing this event.
+ * @param opts - Values for the event.
+ * @param opts.type - The event.type
+ * @param opts.room - The event.room_id
+ * @param opts.sender - The event.sender
+ * @param opts.skey - Optional. The state key (auto inserts empty string)
+ * @param opts.content - The event.content
+ * @param opts.event - True to make a MatrixEvent.
+ * @param client - If passed along with opts.event=true will be used to set up re-emitters.
+ * @returns a JSON object representing this event.
  */
 export function mkEvent(opts: IEventOpts & { event: true }, client?: MatrixClient): MatrixEvent;
 export function mkEvent(opts: IEventOpts & { event?: false }, client?: MatrixClient): Partial<IEvent>;
@@ -160,8 +160,8 @@ interface IPresenceOpts {
 
 /**
  * Create an m.presence event.
- * @param {Object} opts Values for the presence.
- * @return {Object|MatrixEvent} The event
+ * @param opts - Values for the presence.
+ * @returns The event
  */
 export function mkPresence(opts: IPresenceOpts & { event: true }): MatrixEvent;
 export function mkPresence(opts: IPresenceOpts & { event?: false }): Partial<IEvent>;
@@ -193,16 +193,16 @@ interface IMembershipOpts {
 
 /**
  * Create an m.room.member event.
- * @param {Object} opts Values for the membership.
- * @param {string} opts.room The room ID for the event.
- * @param {string} opts.mship The content.membership for the event.
- * @param {string} opts.sender The sender user ID for the event.
- * @param {string} opts.skey The target user ID for the event if applicable
+ * @param opts - Values for the membership.
+ * @param opts.room - The room ID for the event.
+ * @param opts.mship - The content.membership for the event.
+ * @param opts.sender - The sender user ID for the event.
+ * @param opts.skey - The target user ID for the event if applicable
  * e.g. for invites/bans.
- * @param {string} opts.name The content.displayname for the event.
- * @param {string} opts.url The content.avatar_url for the event.
- * @param {boolean} opts.event True to make a MatrixEvent.
- * @return {Object|MatrixEvent} The event
+ * @param opts.name - The content.displayname for the event.
+ * @param opts.url - The content.avatar_url for the event.
+ * @param opts.event - True to make a MatrixEvent.
+ * @returns The event
  */
 export function mkMembership(opts: IMembershipOpts & { event: true }): MatrixEvent;
 export function mkMembership(opts: IMembershipOpts & { event?: false }): Partial<IEvent>;
@@ -250,13 +250,13 @@ export interface IMessageOpts {
 
 /**
  * Create an m.room.message event.
- * @param {Object} opts Values for the message
- * @param {string} opts.room The room ID for the event.
- * @param {string} opts.user The user ID for the event.
- * @param {string} opts.msg Optional. The content.body for the event.
- * @param {boolean} opts.event True to make a MatrixEvent.
- * @param {MatrixClient} client If passed along with opts.event=true will be used to set up re-emitters.
- * @return {Object|MatrixEvent} The event
+ * @param opts - Values for the message
+ * @param opts.room - The room ID for the event.
+ * @param opts.user - The user ID for the event.
+ * @param opts.msg - Optional. The content.body for the event.
+ * @param opts.event - True to make a MatrixEvent.
+ * @param client - If passed along with opts.event=true will be used to set up re-emitters.
+ * @returns The event
  */
 export function mkMessage(opts: IMessageOpts & { event: true }, client?: MatrixClient): MatrixEvent;
 export function mkMessage(opts: IMessageOpts & { event?: false }, client?: MatrixClient): Partial<IEvent>;
@@ -290,14 +290,14 @@ interface IReplyMessageOpts extends IMessageOpts {
 /**
  * Create a reply message.
  *
- * @param {Object} opts Values for the message
- * @param {string} opts.room The room ID for the event.
- * @param {string} opts.user The user ID for the event.
- * @param {string} opts.msg Optional. The content.body for the event.
- * @param {MatrixEvent} opts.replyToMessage The replied message
- * @param {boolean} opts.event True to make a MatrixEvent.
- * @param {MatrixClient} client If passed along with opts.event=true will be used to set up re-emitters.
- * @return {Object|MatrixEvent} The event
+ * @param opts - Values for the message
+ * @param opts.room - The room ID for the event.
+ * @param opts.user - The user ID for the event.
+ * @param opts.msg - Optional. The content.body for the event.
+ * @param opts.replyToMessage - The replied message
+ * @param opts.event - True to make a MatrixEvent.
+ * @param client - If passed along with opts.event=true will be used to set up re-emitters.
+ * @returns The event
  */
 export function mkReplyMessage(opts: IReplyMessageOpts & { event: true }, client?: MatrixClient): MatrixEvent;
 export function mkReplyMessage(opts: IReplyMessageOpts & { event?: false }, client?: MatrixClient): Partial<IEvent>;
@@ -329,8 +329,6 @@ export function mkReplyMessage(
 
 /**
  * A mock implementation of webstorage
- *
- * @constructor
  */
 export class MockStorageApi implements Storage {
     private data: Record<string, any> = {};
@@ -363,8 +361,7 @@ export class MockStorageApi implements Storage {
 /**
  * If an event is being decrypted, wait for it to finish being decrypted.
  *
- * @param {MatrixEvent} event
- * @returns {Promise} promise which resolves (to `event`) when the event has been decrypted
+ * @returns promise which resolves (to `event`) when the event has been decrypted
  */
 export async function awaitDecryption(
     event: MatrixEvent, { waitOnDecryptionFailure = false } = {},

spec/unit/room.spec.ts

@@ -16,7 +16,6 @@ limitations under the License.
 
 /**
  * This is an internal module. See {@link MatrixClient} for the public class.
- * @module client
  */
 
 import { mocked } from "jest-mock";