Apply suggestions from code review

Co-authored-by: LJ <81748770+elle-j@users.noreply.github.com>
Co-authored-by: Kenneth Geisshirt <kenneth.geisshirt@mongodb.com>

packages/realm/src/Dictionary.ts

@@ -270,7 +270,7 @@ export class Dictionary<T = unknown> extends Collection<string, T, [string, T],
    * Adds one or more elements with the specified key and value to the dictionary or updates value if key exists.
    * @param elementsOrKey The element to add or the key of the element to add.
    * @param value - The value of the element to add.
-   * @throws an {@link AssertionError} If not inside a write transaction, if using symbol as keys, or if any value violates type constraints.
+   * @throws An {@link AssertionError} if not inside a write transaction, if using symbol as keys, or if any value violates type constraints.
    * @returns The dictionary.
    * @since 10.6.0
    */

packages/realm/src/List.ts

@@ -99,7 +99,7 @@ export class List<T = unknown> extends OrderedCollection<T> implements Partially
   }
 
   /**
-   * @returns The number of values.
+   * @returns The number of values in the list.
    */
   get length(): number {
     return this.internal.size;

packages/realm/src/Results.ts

@@ -84,7 +84,7 @@ export class Results<T = unknown> extends OrderedCollection<T> {
   }
 
   /*
-   * @returns a string representation of the query and sorting bound to the results.
+   * @returns A string representation of the query and sorting bound to the results.
    */
   description(): string {
     return binding.Helpers.getResultsDescription(this.internal);

packages/realm/src/Set.ts

@@ -57,7 +57,7 @@ export class RealmSet<T = unknown> extends OrderedCollection<T, [T, T]> {
     });
   }
   /**
-   * @returns The number of items in the Set.
+   * @returns The number of values in the Set.
    */
   get size(): number {
     return this.length;
@@ -119,7 +119,7 @@ export class RealmSet<T = unknown> extends OrderedCollection<T, [T, T]> {
   }
 
   /**
-   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/entries
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/entries | Set.prototype.entries()}
    * @returns An iterator over the entries of the Set. Each entry is a two-element array
    * containing the value from the Set, followed by a copy of the same value (`[value, value]`).
    */

packages/realm/src/app-services/App.ts

@@ -234,8 +234,10 @@ export class App<FunctionsFactoryType = DefaultFunctionsFactory, CustomDataType
   /**
    * Log in a user.
    * @param credentials - A credentials object describing the type of authentication provider and its parameters.
+   * @returns A promise that resolves to the logged in {@link User}.
+   * @throws An {@link Error} if the login failed.
    */
-  public async logIn(credentials: Credentials) {
+  public async logIn(credentials: Credentials): Promise<User<FunctionsFactoryType, CustomDataType>> {
     const userInternal = await this.internal.logInWithCredentials(credentials.internal);
     return User.get(userInternal, this);
   }
@@ -252,7 +254,7 @@ export class App<FunctionsFactoryType = DefaultFunctionsFactory, CustomDataType
 
   /**
    * The last user to log in or being switched to.
-   * @returns A {@link User} object representing the currently logged in user. If no user is logged in, null is returned.
+   * @returns A {@link User} object representing the currently logged in user. If no user is logged in, `null` is returned.
    */
   public get currentUser(): User<FunctionsFactoryType, CustomDataType> | null {
     const currentUser = this.internal.currentUser;
@@ -298,15 +300,15 @@ export class App<FunctionsFactoryType = DefaultFunctionsFactory, CustomDataType
    * This includes login, logout, switching users, linking users and refreshing custom data.
    * @param callback - A callback function that will be called when the event occurs.
    */
-  public addListener(callback: AppChangeCallback) {
+  public addListener(callback: AppChangeCallback): void {
     this.listeners.add(callback);
   }
 
   /**
    * Removes an event listener previously added via {@link App.addListener}.
    * @param callback - The callback to remove.
    */
-  public removeListener(callback: AppChangeCallback) {
+  public removeListener(callback: AppChangeCallback): void {
     this.listeners.remove(callback);
   }
 

packages/realm/src/app-services/EmailPasswordAuth.ts

@@ -34,7 +34,7 @@ export class EmailPasswordAuth {
   /**
    * Registers a new email identity with the email/password provider,
    * and sends a confirmation email to the provided address.
-   * @param details - The new user's email and password details
+   * @param details - The new user's email and password details.
    * @param details.email - The email address of the user to register.
    * @param details.password - The password that the user created for the new username/password identity.
    * @since v10.10.0
@@ -57,7 +57,7 @@ export class EmailPasswordAuth {
   /**
    * Re-sends a confirmation email to a user that has registered but
    * not yet confirmed their email address.
-   * @param details - The associated email details
+   * @param details - The associated email details.
    * @param details.email - The email address of the user to re-send a confirmation for.
    * @since v10.10.0
    */
@@ -68,7 +68,7 @@ export class EmailPasswordAuth {
   /**
    * Re-run the custom confirmation function for user that has registered but
    * not yet confirmed their email address.
-   * @param details - The associated email details
+   * @param details - The associated email details.
    * @param details.email - The email address of the user to re-run the confirmation for.
    * @since v10.10.0
    */
@@ -78,7 +78,7 @@ export class EmailPasswordAuth {
 
   /**
    * Resets the password of an email identity using the password reset token emailed to a user.
-   * @param details - The token and password details for the reset
+   * @param details - The token and password details for the reset.
    * @param details.password - The desired new password.
    * @param details.token - The password reset token that was emailed to the user.
    * @param details.tokenId - The password reset token id that was emailed to the user.
@@ -90,7 +90,7 @@ export class EmailPasswordAuth {
 
   /**
    * Sends an email to the user for resetting the password.
-   * @param details - The email details to send the reset to
+   * @param details - The email details to send the reset to.
    * @param details.email - The email address of the user to re-send a confirmation for.
    * @since v10.10.0
    */
@@ -100,7 +100,7 @@ export class EmailPasswordAuth {
 
   /**
    * Call the custom function to reset the password.
-   * @param details - The new user's email and password details
+   * @param details - The new user's email and password details.
    * @param details.email - The email address of the user to register.
    * @param details.password - The password that the user created for the new username/password identity.
    * @param args One or more arguments to pass to the function.

packages/realm/src/app-services/MongoDBCollection.ts

@@ -540,7 +540,7 @@ export class MongoDBCollection<T extends Document> {
    * Inserts a single document into the collection.
    * Note: If the document is missing an _id, one will be generated for it by the server.
    * @param document - The document to insert.
-   * @returns A promise that resolves an object containing the inserted object id (insertedId).
+   * @returns A promise that resolves an object containing the inserted object id (`insertedId`).
    */
   insertOne(document: NewDocument<T>): Promise<InsertOneResult<T["_id"]>> {
     return this.functions.insertOne({
@@ -554,7 +554,7 @@ export class MongoDBCollection<T extends Document> {
    * Inserts an array of documents into the collection.
    * If any values are missing identifiers, they will be generated by the server.
    * @param documents - The array of documents to insert.
-   * @returns A promise that resolves to an object containing an array of ids inserted (insertedIds).
+   * @returns A promise that resolves to an object containing an array of ids inserted (`insertedIds`).
    */
   insertMany(documents: NewDocument<T>[]): Promise<InsertManyResult<T["_id"]>> {
     return this.functions.insertMany({
@@ -567,7 +567,7 @@ export class MongoDBCollection<T extends Document> {
   /**
    * Deletes a single matching document from the collection.
    * @param filter - A filter applied to narrow down the result.
-   * @returns A promise that resolves to an object containing the number of deleted documents (deletedCount).
+   * @returns A promise that resolves to an object containing the number of deleted documents (`deletedCount`).
    */
   deleteOne(filter: Filter = {}): Promise<DeleteResult> {
     return this.functions.deleteOne({
@@ -581,7 +581,7 @@ export class MongoDBCollection<T extends Document> {
    * Deletes multiple documents.
    * @param filter - A filter applied to narrow down the result. If omitted, it defaults
    *  to `{}` which deletes all documents in the collection.
-   * @returns A promise that resolves to an object containing the number of deleted documents (deletedCount).
+   * @returns A promise that resolves to an object containing the number of deleted documents (`deletedCount`).
    */
   deleteMany(filter: Filter = {}): Promise<DeleteResult> {
     return this.functions.deleteMany({
@@ -597,11 +597,13 @@ export class MongoDBCollection<T extends Document> {
    * @param update - The new values for the document.
    * @param options - Additional options to apply.
    * @returns A promise that resolves to an object containing:
+   * ```
    * {
    *  matchedCount: number;
    *  modifiedCount: number;
    *  upsertedId: IdType | undefined;
    * }
+   * ```
    */
   updateOne(filter: Filter, update: Update, options: UpdateOptions = {}): Promise<UpdateResult<T["_id"]>> {
     return this.functions.updateOne({
@@ -620,11 +622,13 @@ export class MongoDBCollection<T extends Document> {
    * @param update - The new values for the documents.
    * @param options - Additional options to apply.
    * @returns A promise that resolves to an object containing:
+   * ```
    * {
    *  matchedCount: number;
    *  modifiedCount: number;
    *  upsertedId: IdType | undefined;
    * }
+   * ```
    */
   updateMany(filter: Filter, update: Update, options: UpdateOptions = {}): Promise<UpdateResult<T["_id"]>> {
     return this.functions.updateMany({

packages/realm/src/app-services/MutableSubscriptionSet.ts

@@ -103,7 +103,7 @@ export class MutableSubscriptionSet extends BaseSubscriptionSet {
    * for example: `mutableSubs.add(realm.objects("Cat").filtered("age > 10"));`.
    * @param query - A {@link Results} instance representing the query to subscribe to.
    * @param options - An optional {@link SubscriptionOptions} object containing options to
-   *  use when adding this subscription (e.g. to give the subscription a name).
+   * use when adding this subscription (e.g. to give the subscription a name).
    * @returns A `Subscription` instance for the new subscription.
    */
   add(query: AnyResults, options?: SubscriptionOptions): Subscription {

packages/realm/src/app-services/PushClient.ts

@@ -34,18 +34,18 @@ export class PushClient {
 
   /**
    * Register this device with the user.
-   * @param token A Firebase Cloud Messaging (FCM) token, retrieved via the firebase SDK.
+   * @param token - A Firebase Cloud Messaging (FCM) token, retrieved via the firebase SDK.
    * @returns A promise that resolves once the device has been registered.
    */
-  async register(token: string) {
+  async register(token: string): Promise<void> {
     await this.internal.registerDevice(token, this.user);
   }
 
   /**
    * Deregister this device with the user, to disable sending messages to this device.
    * @returns A promise that resolves once the device has been deregistered.
    */
-  async deregister() {
+  async deregister(): Promise<void> {
     await this.internal.deregisterDevice(this.user);
   }
 }

packages/realm/src/app-services/Subscription.ts

@@ -57,7 +57,7 @@ export class Subscription {
   /**
    * The name given to this subscription when it was created.
    * If no name was set, this will be `null`.
-   * @returns The name of the subscription or null.
+   * @returns The name of the subscription or `null` if unnamed.
    */
   get name(): string | null {
     const result = this.internal.name;

packages/realm/src/app-services/SyncSession.ts

@@ -418,9 +418,9 @@ export class SyncSession {
   /**
    * Unregister a progress notification callback that was previously registered with {@link addProgressNotification}.
    * Calling the function multiple times with the same callback is ignored.
-   * @param callback - A previously registered progress callback
+   * @param callback - A previously registered progress callback.
    */
-  removeProgressNotification(callback: ProgressNotificationCallback) {
+  removeProgressNotification(callback: ProgressNotificationCallback): void {
     PROGRESS_LISTENERS.remove(callback);
   }
   /**
@@ -439,7 +439,7 @@ export class SyncSession {
    * Calling the function multiple times with the same callback is ignored.
    * @param callback - A previously registered state callback.
    */
-  removeConnectionNotification(callback: ConnectionNotificationCallback) {
+  removeConnectionNotification(callback: ConnectionNotificationCallback): void {
     CONNECTION_LISTENERS.remove(callback);
   }
 

packages/realm/src/app-services/User.ts

@@ -147,7 +147,7 @@ export class User<
 
   /**
    * The id of the device.
-   * @returns The device id as a string or null.
+   * @returns The device id as a string or `null`.
    */
   get deviceId(): string | null {
     return this.internal.deviceId;
@@ -173,7 +173,7 @@ export class User<
 
   /**
    * The logged in state of the user.
-   * @returns True if the user is logged in, false otherwise.
+   * @returns `true` if the user is logged in, `false` otherwise.
    */
   get isLoggedIn(): boolean {
     return this.internal.isLoggedIn;
@@ -192,15 +192,15 @@ export class User<
 
   /**
    * The access token used when requesting a new access token.
-   * @returns The access token as a string or null.
+   * @returns The access token as a string or `null`.
    */
   get accessToken(): string | null {
     return this.internal.accessToken;
   }
 
   /**
    * The refresh token used when requesting a new access token.
-   * @returns The refresh token as a string or null.
+   * @returns The refresh token as a string or `null`.
    */
   get refreshToken(): string | null {
     return this.internal.refreshToken;
@@ -264,13 +264,13 @@ export class User<
    * @param credentials - The credentials to use when linking.
    * @returns A promise that resolves once the user has been linked with the credentials.
    */
-  async linkCredentials(credentials: Credentials) {
+  async linkCredentials(credentials: Credentials): Promise<void> {
     await this.app.internal.linkUser(this.internal, credentials.internal);
   }
 
   /**
    * Call a remote Atlas App Services Function by its name.
-   * Note: Consider using `functions[name]()` instead of calling this method.
+   * @note Consider using `functions[name]()` instead of calling this method.
    * @param name - Name of the App Services Function.
    * @param args - Arguments passed to the Function.
    * @returns A promise that resolves to the value returned by the Function.
@@ -317,7 +317,7 @@ export class User<
 
   /**
    * Refresh the access token and derive custom data from it.
-   * @returns A Promise that resolves to the refreshed custom data.
+   * @returns A promise that resolves to the refreshed custom data.
    */
   async refreshCustomData(): Promise<CustomDataType> {
     await this.app.internal.refreshCustomData(this.internal);
@@ -335,7 +335,7 @@ export class User<
   }
 
   /**
-   * @param serviceName The name of the MongoDB service to connect to.
+   * @param serviceName - The name of the MongoDB service to connect to.
    * @returns A client enabling access to a {@link MongoDB} service.
    * @example
    * let blueWidgets = user.mongoClient("myService")