From b9d0596dd7f5add3f1f6de0c3ae64a4f6f849f08 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Wed, 12 Apr 2023 21:30:57 +0100
Subject: [PATCH] Fix typedoc warnings (#3275)

There aren't that many of these, so I've gone through and fixed them, and
configured the GHA workflow to complain if any creep back in.
---
 .github/workflows/static_analysis.yml |  2 +-
 src/client.ts                         |  2 +-
 src/crypto/index.ts                   | 14 ++++++--------
 src/crypto/store/base.ts              |  2 +-
 src/interactive-auth.ts               |  2 +-
 src/matrix.ts                         |  4 +++-
 src/models/room.ts                    |  2 +-
 7 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/static_analysis.yml b/.github/workflows/static_analysis.yml
index 62681ff07..4fa2361c3 100644
--- a/.github/workflows/static_analysis.yml
+++ b/.github/workflows/static_analysis.yml
@@ -65,7 +65,7 @@ jobs:
               run: "yarn install"
 
             - name: Generate Docs
-              run: "yarn run gendoc"
+              run: "yarn run gendoc --treatWarningsAsErrors"
 
             - name: Upload Artifact
               uses: actions/upload-artifact@v3
diff --git a/src/client.ts b/src/client.ts
index ddad114f1..309817f87 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -2278,7 +2278,7 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
      * @param userIds - The users to fetch.
      * @param forceDownload - Always download the keys even if cached.
      *
-     * @returns A promise which resolves to a map userId-\>deviceId-\>{@link DeviceInfo}
+     * @returns A promise which resolves to a map userId-\>deviceId-\>`DeviceInfo`
      */
     public downloadKeys(userIds: string[], forceDownload?: boolean): Promise<DeviceInfoMap> {
         if (!this.crypto) {
diff --git a/src/crypto/index.ts b/src/crypto/index.ts
index 6f06fb19f..6d860c6d2 100644
--- a/src/crypto/index.ts
+++ b/src/crypto/index.ts
@@ -245,8 +245,8 @@ export enum CryptoEvent {
 export type CryptoEventHandlerMap = {
     /**
      * Fires when a device is marked as verified/unverified/blocked/unblocked by
-     * {@link MatrixClient#setDeviceVerified|MatrixClient.setDeviceVerified} or
-     * {@link MatrixClient#setDeviceBlocked|MatrixClient.setDeviceBlocked}.
+     * {@link MatrixClient#setDeviceVerified | MatrixClient.setDeviceVerified} or
+     * {@link MatrixClient#setDeviceBlocked | MatrixClient.setDeviceBlocked}.
      *
      * @param userId - the owner of the verified device
      * @param deviceId - the id of the verified device
@@ -1778,8 +1778,7 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
      *
      * @param value - whether to blacklist all unverified devices by default
      *
-     * @deprecated For external code, use {@link MatrixClient#setGlobalBlacklistUnverifiedDevices}. For
-     *   internal code, set {@link MatrixClient#globalBlacklistUnverifiedDevices} directly.
+     * @deprecated Set {@link CryptoApi#globalBlacklistUnverifiedDevices | CryptoApi.globalBlacklistUnverifiedDevices} directly.
      */
     public setGlobalBlacklistUnverifiedDevices(value: boolean): void {
         this.globalBlacklistUnverifiedDevices = value;
@@ -1788,8 +1787,7 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
     /**
      * @returns whether to blacklist all unverified devices by default
      *
-     * @deprecated For external code, use {@link MatrixClient#getGlobalBlacklistUnverifiedDevices}. For
-     *   internal code, reference {@link MatrixClient#globalBlacklistUnverifiedDevices} directly.
+     * @deprecated Reference {@link CryptoApi#globalBlacklistUnverifiedDevices | CryptoApi.globalBlacklistUnverifiedDevices} directly.
      */
     public getGlobalBlacklistUnverifiedDevices(): boolean {
         return this.globalBlacklistUnverifiedDevices;
@@ -2666,7 +2664,7 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
      *
      * @returns resolves once the sessions are complete, to
      *    an Object mapping from userId to deviceId to
-     *    {@link OlmSessionResult}
+     *    `IOlmSessionResult`
      */
     public ensureOlmSessionsForUsers(
         users: string[],
@@ -3767,7 +3765,7 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
      *
      * @param algorithm -  crypto algorithm
      *
-     * @throws {@link DecryptionError} if the algorithm is unknown
+     * @throws `DecryptionError` if the algorithm is unknown
      */
     public getRoomDecryptor(roomId: string | null, algorithm: string): DecryptionAlgorithm {
         let decryptors: Map<string, DecryptionAlgorithm> | undefined;
diff --git a/src/crypto/store/base.ts b/src/crypto/store/base.ts
index 4c88ec287..8657c9392 100644
--- a/src/crypto/store/base.ts
+++ b/src/crypto/store/base.ts
@@ -211,7 +211,7 @@ export interface OutgoingRoomKeyRequest {
      */
     requestBody: IRoomKeyRequestBody;
     /**
-     * current state of this request (states are defined in {@link OutgoingRoomKeyRequestManager})
+     * current state of this request
      */
     state: RoomKeyRequestState;
 }
diff --git a/src/interactive-auth.ts b/src/interactive-auth.ts
index 7d9c183f5..a222d8479 100644
--- a/src/interactive-auth.ts
+++ b/src/interactive-auth.ts
@@ -97,7 +97,7 @@ export interface IAuthDict {
     token?: string;
 }
 
-class NoAuthFlowFoundError extends Error {
+export class NoAuthFlowFoundError extends Error {
     public name = "NoAuthFlowFoundError";
 
     // eslint-disable-next-line @typescript-eslint/naming-convention, camelcase
diff --git a/src/matrix.ts b/src/matrix.ts
index 591c5e359..4df341ea6 100644
--- a/src/matrix.ts
+++ b/src/matrix.ts
@@ -47,6 +47,7 @@ export * from "./store/memory";
 export * from "./store/indexeddb";
 export * from "./crypto/store/memory-crypto-store";
 export * from "./crypto/store/indexeddb-crypto-store";
+export { OutgoingRoomKeyRequest } from "./crypto/store/base";
 export * from "./content-repo";
 export * from "./@types/event";
 export * from "./@types/PushRules";
@@ -62,13 +63,14 @@ export type { MatrixCall } from "./webrtc/call";
 export { GroupCallEvent, GroupCallIntent, GroupCallState, GroupCallType } from "./webrtc/groupCall";
 export type { GroupCall } from "./webrtc/groupCall";
 export type { CryptoApi } from "./crypto-api";
+export { CryptoEvent } from "./crypto";
 
 let cryptoStoreFactory = (): CryptoStore => new MemoryCryptoStore();
 
 /**
  * Configure a different factory to be used for creating crypto stores
  *
- * @param fac - a function which will return a new {@link CryptoStore}
+ * @param fac - a function which will return a new `CryptoStore`
  */
 export function setCryptoStoreFactory(fac: () => CryptoStore): void {
     cryptoStoreFactory = fac;
diff --git a/src/models/room.ts b/src/models/room.ts
index 4eb5fca98..e36114a44 100644
--- a/src/models/room.ts
+++ b/src/models/room.ts
@@ -1923,7 +1923,7 @@ export class Room extends ReadReceipt<RoomEmittedEvents, RoomEventHandlerMap> {
     /**
      * Processes poll events:
      * If the event has a decryption failure, it will listen for decryption and tries again.
-     * If it is a poll start event ({@link M_POLL_START}),
+     * If it is a poll start event (`m.poll.start`),
      * it creates and stores a Poll model and emits a PollEvent.New event.
      * If the event is related to a poll, it will add it to the poll.
      * Noop for other cases.