update docs

Author: W-A-James

src/cursor/run_command_cursor.ts

@@ -23,7 +23,35 @@ export type RunCursorCommandOptions = {
    * `maxTimeMS` is provided in the command in addition to setting `timeoutMS` in the options, then
    * the original value of `maxTimeMS` will be overwritten. */
   timeoutMS?: number;
-  /** See {@link CursorTimeoutMode} */
+  /** @public
+   * 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.
+   *
+   * Depending on the type of cursor being used, this option has different default values.
+   * For non-tailable cursors, this value defaults to `'cursorLifetime'`
+   * For tailable cursors, this value defaults to `'iteration'` since tailable cursors, by
+   * definition can have an arbitrarily long lifetime.
+   *
+   * @example
+   * # Example showing use of `'iteration'`
+   * ```ts
+   * const cursor = collection.find({}, {timeoutMS: 100, timeoutMode: 'iteration'});
+   * for await (const doc of cursor) {
+   *  // process doc
+   *  // This will throw a timeout error if any of the iterator's `next()` calls takes more than 100ms, but
+   * will continue to iterate successfully otherwise, regardless of the number of batches.
+   * }
+   * ```
+   *
+   * # Example showing use of `'cursorLifetime'`
+   *
+   * ```ts
+   * const cursor = collection.find({}, { timeoutMS: 1000, timeoutMode: 'cursorLifetime' });
+   * const docs = await cursor.toArray(); // This entire line will throw a timeout error if all batches are not fetched and returned within 1000ms.
+   * ```
+   */
   timeoutMode?: CursorTimeoutMode;
   tailable?: boolean;
   awaitData?: boolean;

src/gridfs/index.ts

@@ -38,9 +38,8 @@ 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. 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?*/
+  /** Specifies the lifetime duration of a gridFS stream. If any async operations are in progress
+   * when this timeout expires, the stream will throw a timeout error. */
   timeoutMS?: number;
 }
 

src/operations/indexes.ts

@@ -1,7 +1,7 @@
 import type { Document } from '../bson';
 import { CursorResponse } from '../cmap/wire_protocol/responses';
 import type { Collection } from '../collection';
-import { type AbstractCursorOptions, type CursorTimeoutMode } from '../cursor/abstract_cursor';
+import { type AbstractCursorOptions } from '../cursor/abstract_cursor';
 import { MongoCompatibilityError } from '../error';
 import { type OneOrMore } from '../mongo_types';
 import type { Server } from '../sdam/server';