WIP API docs

Author: W-A-James

src/cursor/abstract_cursor.ts

@@ -142,14 +142,17 @@ export interface AbstractCursorOptions extends BSONSerializeOptions {
    */
   awaitData?: boolean;
   noCursorTimeout?: boolean;
-  /** Specifies the time an operation will run until it throws a timeout error. See {@link AbstractCursorOptions.timeoutMode} for more details. */
+  /** Specifies the time an operation will run until it throws a timeout error. See {@link AbstractCursorOptions.timeoutMode} for more details on how this option applies to cursors. */
   timeoutMS?: number;
   /**
    * Specifies how `timeoutMS` is applied to the cursor. Can be either `'cursorLifeTime'` or `'iteration'`
    * When set to `'iteration'`, the deadline specified by `timeoutMS` applies to each call of
    * `cursor.next()`.
    * When set to `'cursorLifetime'`, the deadline applies to the life of the entire cursor.
    *
+   * Note that the use of '`cursorLifetime`' should be limited to relatively short-lived cursors as
+   * it has the potential to hang on an operation for the entirety of `timeoutMS`.
+   *
    * @example
    * # Example showing use of `'iteration'`
    * ```ts

src/gridfs/index.ts

@@ -38,7 +38,9 @@ export interface GridFSBucketOptions extends WriteConcernOptions {
   chunkSizeBytes?: number;
   /** Read preference to be passed to read operations */
   readPreference?: ReadPreference;
-  /** Specifies the time an operation will run until it throws a timeout error */
+  /** Specifies the time an operation will run until it throws a timeout error. Note that the
+  * deadline specified by this option may be breached if calls to interact with the stream take
+    * longer than the remaining timeout. FIXME(NODE-6456): what does this even mean?*/
   timeoutMS?: number;
 }
 

src/operations/operation.ts

@@ -61,9 +61,9 @@ export abstract class AbstractOperation<TResult = any> {
 
   options: OperationOptions;
 
-  /** @internal */
+  /** @internal TODO(NODE-6197): remove dead code */
   timeout?: Timeout;
-  /** @internal */
+  /** Specifies the time an operation will run until it throws a timeout error.*/
   timeoutMS?: number;
 
   [kSession]: ClientSession | undefined;

src/operations/run_command.ts

@@ -15,7 +15,7 @@ export type RunCommandOptions = {
   session?: ClientSession;
   /** The read preference */
   readPreference?: ReadPreferenceLike;
-  /** @internal */
+  /** Specifies the time an operation will run until it throws a timeout error */
   timeoutMS?: number;
   /** @internal */
   omitMaxTimeMS?: boolean;

src/sessions.ts

@@ -103,7 +103,7 @@ export interface EndSessionOptions {
   force?: boolean;
   forceClear?: boolean;
 
-  /** @internal */
+  /** Specifies the time an operation will run until it throws a timeout error */
   timeoutMS?: number;
 }
 
@@ -145,7 +145,7 @@ export class ClientSession
   [kPinnedConnection]?: Connection;
   /** @internal */
   [kTxnNumberIncrement]: number;
-  /** @internal */
+  /** Specifies the time an operation in a given `ClientSession` will run until it throws a timeout error */
   timeoutMS?: number;
 
   /** @internal */
@@ -709,6 +709,8 @@ export class ClientSession
    * **IMPORTANT:** Running operations in parallel is not supported during a transaction. The use of `Promise.all`,
    * `Promise.allSettled`, `Promise.race`, etc to parallelize operations inside a transaction is
    * undefined behaviour.
+     *
+     * **IMPORTANT:** When running a 
    *
    *
    * @remarks