Update typedoc (matrix-org#4098)

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: Michael Telatynski <[email protected]>

.eslintignore

@@ -0,0 +1 @@
+_docs

.eslintrc.js

@@ -103,11 +103,8 @@ module.exports = {
             },
         },
         {
-            // We don't need amazing docs in our spec files
             files: ["src/**/*.ts"],
             rules: {
-                "tsdoc/syntax": "error",
-                // We use some select jsdoc rules as the tsdoc linter has only one rule
                 "jsdoc/no-types": "error",
                 "jsdoc/empty-tags": "error",
                 "jsdoc/check-property-names": "error",

.github/workflows/release.yml

@@ -39,12 +39,6 @@ jobs:
             - name: 🧮 Checkout code
               uses: actions/checkout@v4
 
-            - name: 🧮 Checkout gh-pages
-              uses: actions/checkout@v4
-              with:
-                  ref: gh-pages
-                  path: _docs
-
             - name: 🔧 Yarn cache
               uses: actions/setup-node@v4
               with:
@@ -53,26 +47,21 @@ jobs:
             - name: 🔨 Install dependencies
               run: "yarn install --frozen-lockfile"
 
-            - name: 🔨 Install symlinks
-              run: |
-                  sudo apt-get update
-                  sudo apt-get install -y symlinks
-
             - name: 📖 Generate docs
-              run: |
-                  yarn tpv purge --yes --out _docs --stale --major 10
-                  yarn gendoc
-                  symlinks -rc _docs
-                  find _docs -xtype l -delete
+              run: yarn gendoc
 
-            - name: 🔨 Set up git
-              run: |
-                  git config --global user.email "[email protected]"
-                  git config --global user.name "RiotRobot"
+            - name: Upload artifact
+              uses: actions/upload-pages-artifact@v3
+              with:
+                  path: _docs
 
-            - name: 🚀 Deploy
-              run: |
-                  git add . --all
-                  git commit -m "Update docs"
-                  git push
-              working-directory: _docs
+    docs-deploy:
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+        runs-on: ubuntu-latest
+        needs: docs
+        steps:
+            - name: Deploy to GitHub Pages
+              id: deployment
+              uses: actions/deploy-pages@v4

.github/workflows/static_analysis.yml

@@ -83,13 +83,6 @@ jobs:
             - name: Generate Docs
               run: "yarn run gendoc --treatWarningsAsErrors"
 
-            # Upload artifact duplicates symlink contents so we do this to save 75% space
-            - name: Flatten symlink and write _redirects
-              run: |
-                  find _docs -mindepth 1 -maxdepth 1 ! -type f ! -name stable -printf '/%f/* /stable/:splat\n' > _docs/_redirects
-                  find _docs -mindepth 1 -maxdepth 1 -type l -delete
-                  find _docs -mindepth 1 -maxdepth 1 -type d -execdir mv {} stable \; -quit
-
             - name: Upload Artifact
               uses: actions/upload-artifact@v4
               with:

README.md

@@ -294,7 +294,7 @@ host the API reference from the source files like this:
 
 ```
   $ yarn gendoc
-  $ cd _docs
+  $ cd docs
   $ python -m http.server 8005
 ```
 

package.json

@@ -121,13 +121,11 @@
         "prettier": "3.2.5",
         "rimraf": "^5.0.0",
         "ts-node": "^10.9.1",
-        "typedoc": "^0.24.0",
+        "typedoc": "^0.25.10",
         "typedoc-plugin-coverage": "^3.0.0",
         "typedoc-plugin-mdn-links": "^3.0.3",
         "typedoc-plugin-missing-exports": "^2.0.0",
-        "typedoc-plugin-versions": "^0.2.3",
-        "typedoc-plugin-versions-cli": "^0.1.12",
-        "typescript": "^5.0.0"
+        "typescript": "^5.3.3"
     },
     "@casualbot/jest-sonar-reporter": {
         "outputDirectory": "coverage",

src/@types/requests.ts

@@ -162,11 +162,21 @@ export interface ICreateRoomOpts {
 }
 
 export interface IRoomDirectoryOptions {
+    /**
+     * The remote server to query for the room list.
+     * Optional. If unspecified, get the local homeserver's public room list.
+     */
     server?: string;
+    /**
+     * Maximum number of entries to return
+     */
     limit?: number;
+    /**
+     * Token to paginate from
+     */
     since?: string;
 
-    // Filter parameters
+    /** Filter parameters */
     filter?: {
         // String to search for
         generic_search_term?: string;

src/client.ts

@@ -3286,7 +3286,7 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
      * Encrypts and sends a given object via Olm to-device messages to a given
      * set of devices.
      *
-     * @param userDeviceMap - mapping from userId to deviceInfo
+     * @param userDeviceInfoArr - list of deviceInfo objects representing the devices to send to
      *
      * @param payload - fields to include in the encrypted payload
      *
@@ -7498,7 +7498,6 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
      * store client options with boolean/string/numeric values
      * to know in the next session what flags the sync data was
      * created with (e.g. lazy loading)
-     * @param opts - the complete set of client options
      * @returns for store operation
      */
     public storeClientOptions(): Promise<void> {
@@ -8480,12 +8479,7 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
     }
 
     /**
-     * @param options - Options for this request
-     * @param server - The remote server to query for the room list.
-     *                                Optional. If unspecified, get the local home
-     *                                server's public room list.
-     * @param limit - Maximum number of entries to return
-     * @param since - Token to paginate from
+     * @param params - Options for this request
      * @returns Promise which resolves: IPublicRoomsResponse
      * @returns Rejects: with an error response.
      */
@@ -8601,9 +8595,9 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
 
     /**
      * Query the user directory with a term matching user IDs, display names and domains.
-     * @param term - the term with which to search.
-     * @param limit - the maximum number of results to return. The server will
-     *                 apply a limit if unspecified.
+     * @param options
+     * @param options.term - the term with which to search.
+     * @param options.limit - the maximum number of results to return. The server will apply a limit if unspecified.
      * @returns Promise which resolves: an array of results.
      */
     public searchUserDirectory({ term, limit }: { term: string; limit?: number }): Promise<IUserDirectoryResponse> {
@@ -9008,8 +9002,9 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
 
     /**
      * Perform a server-side search.
-     * @param next_batch - the batch token to pass in the query string
-     * @param body - the JSON object to pass to the request body.
+     * @param params
+     * @param params.next_batch - the batch token to pass in the query string
+     * @param params.body - the JSON object to pass to the request body.
      * @param abortSignal - optional signal used to cancel the http request.
      * @returns Promise which resolves to the search response object.
      * @returns Rejects: with an error response.

src/crypto/OlmDevice.ts

@@ -55,7 +55,14 @@ function checkPayloadLength(payloadString: string): void {
 }
 
 interface IInitOpts {
+    /**
+     * (Optional) data from exported device that must be re-created.
+     * If present, opts.pickleKey is ignored (exported data already provides a pickle key)
+     */
     fromExportedDevice?: IExportedDevice;
+    /**
+     * (Optional) pickle key to set instead of default one
+     */
     pickleKey?: string;
 }
 
@@ -174,11 +181,7 @@ export class OlmDevice {
      *
      * Reads the device keys from the OlmAccount object.
      *
-     * @param fromExportedDevice - (Optional) data from exported device
-     *     that must be re-created.
-     *     If present, opts.pickleKey is ignored
-     *     (exported data already provides a pickle key)
-     * @param pickleKey - (Optional) pickle key to set instead of default one
+     * @param IInitOpts - opts to initialise the OlmAccount with
      */
     public async init({ pickleKey, fromExportedDevice }: IInitOpts = {}): Promise<void> {
         let e2eKeys;

src/crypto/index.ts

@@ -473,8 +473,6 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
      *
      * @param cryptoStore - storage for the crypto layer.
      *
-     * @param roomList - An initialised RoomList object
-     *
      * @param verificationMethods - Array of verification methods to use.
      *    Each element can either be a string from MatrixClient.verificationMethods
      *    or a class that implements a verification method.
@@ -842,15 +840,6 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
      *   secret storage (if it has been setup)
      *
      * The cross-signing API is currently UNSTABLE and may change without notice.
-     *
-     * @param authUploadDeviceSigningKeys - Function
-     * called to await an interactive auth flow when uploading device signing keys.
-     * @param setupNewCrossSigning - Optional. Reset even if keys
-     * already exist.
-     * Args:
-     *     A function that makes the request requiring auth. Receives the
-     *     auth data as an object. Can be called multiple times, first with an empty
-     *     authDict, to obtain the flows.
      */
     public async bootstrapCrossSigning({
         authUploadDeviceSigningKeys,
@@ -964,20 +953,6 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
      *
      * The Secure Secret Storage API is currently UNSTABLE and may change without notice.
      *
-     * @param createSecretStorageKey - Optional. Function
-     * called to await a secret storage key creation flow.
-     *     Returns a Promise which resolves 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.
-     * @param keyBackupInfo - The current key backup object. If passed,
-     * the passphrase and recovery key from this backup will be used.
-     * @param setupNewKeyBackup - If true, a new key backup version will be
-     * created and the private key stored in the new SSSS store. Ignored if keyBackupInfo
-     * is supplied.
-     * @param setupNewSecretStorage - Optional. Reset even if keys already exist.
-     * @param getKeyBackupPassphrase - Optional. Function called to get the user's
-     *     current key backup passphrase. Should return a promise that resolves with a Buffer
-     *     containing the key, or rejects if the key cannot be obtained.
      * Returns:
      *     A promise which resolves to key creation data for
      *     SecretStorage#addKey: an object with `passphrase` etc fields.

src/crypto/verification/request/VerificationRequest.ts

@@ -495,8 +495,9 @@ export class VerificationRequest<C extends IVerificationChannel = IVerificationC
 
     /**
      * Cancels the request, sending a cancellation to the other party
-     * @param reason - the error reason to send the cancellation with
-     * @param code - the error code to send the cancellation with
+     * @param params
+     * @param params.reason - the error reason to send the cancellation with
+     * @param params.code - the error code to send the cancellation with
      * @returns resolves when the event has been sent.
      */
     public async cancel({ reason = "User declined", code = "m.user" } = {}): Promise<void> {

src/http-api/fetch.ts

@@ -111,8 +111,8 @@ export class FetchHttpApi<O extends IHttpOpts> {
      *
      * @param body - The HTTP JSON body.
      *
-     * @param opts - additional options.
-     * When `opts.doNotAttemptTokenRefresh` is true, token refresh will not be attempted
+     * @param paramOpts - additional options.
+     * When `paramOpts.doNotAttemptTokenRefresh` is true, token refresh will not be attempted
      * when an expired token is encountered. Used to only attempt token refresh once.
      *
      * @returns Promise which resolves to

src/matrixrtc/MatrixRTCSession.ts

@@ -610,7 +610,7 @@ export class MatrixRTCSession extends TypedEventEmitter<MatrixRTCSessionEvent, M
 
     /**
      * Constructs our own membership
-     * @param prevEvent - The previous version of our call membership, if any
+     * @param prevMembership - The previous value of our call membership, if any
      */
     private makeMyMembership(prevMembership?: CallMembership): CallMembershipData {
         if (this.relativeExpiry === undefined) {

src/models/event-timeline-set.ts

@@ -159,7 +159,7 @@ export class EventTimelineSet extends TypedEventEmitter<EmittedEvents, EventTime
      * @param client - the Matrix client which owns this EventTimelineSet,
      * can be omitted if room is specified.
      * @param thread - the thread to which this timeline set relates.
-     * @param isThreadTimeline - Whether this timeline set relates to a thread list timeline
+     * @param threadListType - the type of thread list represented, if any
      * (e.g., All threads or My threads)
      */
     public constructor(
@@ -674,6 +674,8 @@ export class EventTimelineSet extends TypedEventEmitter<EmittedEvents, EventTime
      *
      * Will fire "Room.timeline" for each event added.
      *
+     * @param event - the event to add
+     * @param timeline - the timeline onto which to add it
      * @param options - addEventToTimeline options
      *
      * @remarks
@@ -771,8 +773,6 @@ export class EventTimelineSet extends TypedEventEmitter<EmittedEvents, EventTime
      *
      * @internal
      *
-     * @param options - addEventToTimeline options
-     *
      * @remarks
      * Fires {@link RoomEvent.Timeline}
      */

src/models/invites-ignorer.ts

@@ -140,8 +140,9 @@ export class IgnoredInvites {
     /**
      * Find out whether an invite should be ignored.
      *
-     * @param sender - The user id for the user who issued the invite.
-     * @param roomId - The room to which the user is invited.
+     * @param params
+     * @param params.sender - The user id for the user who issued the invite.
+     * @param params.roomId - The room to which the user is invited.
      * @returns A rule matching the entity, if any was found, `null` otherwise.
      */
     public async getRuleForInvite({

src/models/room-receipts.ts

@@ -98,7 +98,7 @@ export class RoomReceipts {
     /**
      * Look for dangling receipts for the given event ID,
      * and add them to the thread of unthread receipts if found.
-     * @param eventId - the event ID to look for
+     * @param event - the event to look for
      */
     private onTimelineEvent = (event: MatrixEvent): void => {
         const eventId = event.getId();

src/models/room-state.ts

@@ -297,13 +297,15 @@ export class RoomState extends TypedEventEmitter<EmittedEvents, EventHandlerMap>
     /**
      * Get state events from the state of the room.
      * @param eventType - The event type of the state event.
-     * @param stateKey - Optional. The state_key of the state event. If
-     * this is `undefined` then all matching state events will be
-     * returned.
-     * @returns A list of events if state_key was
-     * `undefined`, else a single event (or null if no match found).
+     * @returns A list of events
      */
     public getStateEvents(eventType: EventType | string): MatrixEvent[];
+    /**
+     * Get state events from the state of the room.
+     * @param eventType - The event type of the state event.
+     * @param stateKey - The state_key of the state event.
+     * @returns A single event (or null if no match found).
+     */
     public getStateEvents(eventType: EventType | string, stateKey: string): MatrixEvent | null;
     public getStateEvents(eventType: EventType | string, stateKey?: string): MatrixEvent[] | MatrixEvent | null {
         if (!this.events.has(eventType)) {

src/oidc/tokenRefresher.ts

@@ -113,10 +113,10 @@ export class OidcTokenRefresher {
      *
      * This function is intended to be overriden by the consumer when persistence is necessary.
      *
-     * @param accessToken - new access token
-     * @param refreshToken - OPTIONAL new refresh token
+     * @param tokens.accessToken - new access token
+     * @param tokens.refreshToken - OPTIONAL new refresh token
      */
-    public async persistTokens(_tokens: { accessToken: string; refreshToken?: string }): Promise<void> {
+    public async persistTokens(tokens: { accessToken: string; refreshToken?: string }): Promise<void> {
         // NOOP
     }
 

src/sliding-sync-sdk.ts

@@ -455,7 +455,7 @@ export class SlidingSyncSdk {
      * @returns A promise which resolves once the room has been added to the
      * store.
      */
-    public async peek(_roomId: string): Promise<Room> {
+    public async peek(roomId: string): Promise<Room> {
         return null!; // TODO
     }