docs(NODE-5227): add defaults to doc comments (#574)

README.md

@@ -69,35 +69,9 @@ npm install bson
 
 ## Documentation
 
-### Objects
-
-<dl>
-<dt><a href="#EJSON">EJSON</a> : <code>object</code></dt>
-<dd></dd>
-</dl>
-
-### Functions
-
-<dl>
-<dt><a href="#setInternalBufferSize">setInternalBufferSize(size)</a></dt>
-<dd><p>Sets the size of the internal serialization buffer.</p>
-</dd>
-<dt><a href="#serialize">serialize(object)</a> ⇒ <code>Buffer</code></dt>
-<dd><p>Serialize a Javascript object.</p>
-</dd>
-<dt><a href="#serializeWithBufferAndIndex">serializeWithBufferAndIndex(object, buffer)</a> ⇒ <code>Number</code></dt>
-<dd><p>Serialize a Javascript object using a predefined Buffer and index into the buffer, useful when pre-allocating the space for serialization.</p>
-</dd>
-<dt><a href="#deserialize">deserialize(buffer)</a> ⇒ <code>Object</code></dt>
-<dd><p>Deserialize data as BSON.</p>
-</dd>
-<dt><a href="#calculateObjectSize">calculateObjectSize(object)</a> ⇒ <code>Number</code></dt>
-<dd><p>Calculate the bson size for a passed in Javascript object.</p>
-</dd>
-<dt><a href="#deserializeStream">deserializeStream(data, startIndex, numberOfDocuments, documents, docStartIndex, [options])</a> ⇒ <code>Number</code></dt>
-<dd><p>Deserialize stream data as BSON documents.</p>
-</dd>
-</dl>
+### BSON 
+
+[API documentation](https://mongodb.github.io/node-mongodb-native/Next/modules/BSON.html)
 
 <a name="EJSON"></a>
 
@@ -189,103 +163,6 @@ Serializes an object to an Extended JSON string, and reparse it as a JavaScript
 
 Deserializes an Extended JSON object into a plain JavaScript object with native/BSON types
 
-<a name="setInternalBufferSize"></a>
-
-### setInternalBufferSize(size)
-
-| Param | Type | Description |
-| --- | --- | --- |
-| size | <code>number</code> | The desired size for the internal serialization buffer |
-
-Sets the size of the internal serialization buffer.
-
-<a name="serialize"></a>
-
-### serialize(object)
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| object | <code>Object</code> |  | the Javascript object to serialize. |
-| [options.checkKeys] | <code>Boolean</code> |  | the serializer will check if keys are valid. |
-| [options.serializeFunctions] | <code>Boolean</code> | <code>false</code> | serialize the javascript functions **(default:false)**. |
-| [options.ignoreUndefined] | <code>Boolean</code> | <code>true</code> | ignore undefined fields **(default:true)**. |
-
-Serialize a Javascript object.
-
-**Returns**: <code>Buffer</code> - returns the Buffer object containing the serialized object.
-<a name="serializeWithBufferAndIndex"></a>
-
-### serializeWithBufferAndIndex(object, buffer)
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| object | <code>Object</code> |  | the Javascript object to serialize. |
-| buffer | <code>Buffer</code> |  | the Buffer you pre-allocated to store the serialized BSON object. |
-| [options.checkKeys] | <code>Boolean</code> |  | the serializer will check if keys are valid. |
-| [options.serializeFunctions] | <code>Boolean</code> | <code>false</code> | serialize the javascript functions **(default:false)**. |
-| [options.ignoreUndefined] | <code>Boolean</code> | <code>true</code> | ignore undefined fields **(default:true)**. |
-| [options.index] | <code>Number</code> |  | the index in the buffer where we wish to start serializing into. |
-
-Serialize a Javascript object using a predefined Buffer and index into the buffer, useful when pre-allocating the space for serialization.
-
-**Returns**: <code>Number</code> - returns the index pointing to the last written byte in the buffer.
-<a name="deserialize"></a>
-
-### deserialize(buffer)
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| buffer | <code>Buffer</code> |  | the buffer containing the serialized set of BSON documents. |
-| [options.evalFunctions] | <code>Object</code> | <code>false</code> | evaluate functions in the BSON document scoped to the object deserialized. |
-| [options.cacheFunctions] | <code>Object</code> | <code>false</code> | cache evaluated functions for reuse. |
-| [options.useBigInt64] | <code>Object</code> | <code>false</code> | when deserializing a Long will return a BigInt. |
-| [options.promoteLongs] | <code>Object</code> | <code>true</code> | when deserializing a Long will fit it into a Number if it's smaller than 53 bits |
-| [options.promoteBuffers] | <code>Object</code> | <code>false</code> | when deserializing a Binary will return it as a node.js Buffer instance. |
-| [options.promoteValues] | <code>Object</code> | <code>true</code> | when deserializing will promote BSON values to their Node.js closest equivalent types. |
-| [options.fieldsAsRaw] | <code>Object</code> | <code></code> | allow to specify if there what fields we wish to return as unserialized raw buffer. |
-| [options.bsonRegExp] | <code>Object</code> | <code>false</code> | return BSON regular expressions as BSONRegExp instances. |
-| [options.allowObjectSmallerThanBufferSize] | <code>boolean</code> | <code>false</code> | allows the buffer to be larger than the parsed BSON object. |
-
-Deserialize data as BSON.
-
-**Returns**: <code>Object</code> - returns the deserialized Javascript Object.
-<a name="calculateObjectSize"></a>
-
-### calculateObjectSize(object)
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| object | <code>Object</code> |  | the Javascript object to calculate the BSON byte size for. |
-| [options.serializeFunctions] | <code>Boolean</code> | <code>false</code> | serialize the javascript functions **(default:false)**. |
-| [options.ignoreUndefined] | <code>Boolean</code> | <code>true</code> | ignore undefined fields **(default:true)**. |
-
-Calculate the bson size for a passed in Javascript object.
-
-**Returns**: <code>Number</code> - returns the number of bytes the BSON object will take up.
-<a name="deserializeStream"></a>
-
-### deserializeStream(data, startIndex, numberOfDocuments, documents, docStartIndex, [options])
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| data | <code>Buffer</code> |  | the buffer containing the serialized set of BSON documents. |
-| startIndex | <code>Number</code> |  | the start index in the data Buffer where the deserialization is to start. |
-| numberOfDocuments | <code>Number</code> |  | number of documents to deserialize. |
-| documents | <code>Array</code> |  | an array where to store the deserialized documents. |
-| docStartIndex | <code>Number</code> |  | the index in the documents array from where to start inserting documents. |
-| [options] | <code>Object</code> |  | additional options used for the deserialization. |
-| [options.evalFunctions] | <code>Object</code> | <code>false</code> | evaluate functions in the BSON document scoped to the object deserialized. |
-| [options.cacheFunctions] | <code>Object</code> | <code>false</code> | cache evaluated functions for reuse. |
-| [options.promoteLongs] | <code>Object</code> | <code>true</code> | when deserializing a Long will fit it into a Number if it's smaller than 53 bits |
-| [options.promoteBuffers] | <code>Object</code> | <code>false</code> | when deserializing a Binary will return it as a node.js Buffer instance. |
-| [options.promoteValues] | <code>Object</code> | <code>false</code> | when deserializing will promote BSON values to their Node.js closest equivalent types. |
-| [options.fieldsAsRaw] | <code>Object</code> | <code></code> | allow to specify if there what fields we wish to return as unserialized raw buffer. |
-| [options.bsonRegExp] | <code>Object</code> | <code>false</code> | return BSON regular expressions as BSONRegExp instances. |
-
-Deserialize stream data as BSON documents.
-
-**Returns**: <code>Number</code> - returns the next index in the buffer after deserialization **x** numbers of documents.
-
 ## Error Handling
 
 It is our recommendation to use `BSONError.isBSONError()` checks on errors and to avoid relying on parsing `error.message` and `error.name` strings in your code. We guarantee `BSONError.isBSONError()` checks will pass according to semver guidelines, but errors may be sub-classed or their messages may change at any time, even patch releases, as we see fit to increase the helpfulness of the errors.

src/binary.ts

@@ -362,7 +362,7 @@ export class UUID extends Binary {
   /**
    * Returns the UUID id as a 32 or 36 character hex string representation, excluding/including dashes (defaults to 36 character dash separated)
    * @param includeDashes - should the string exclude dash-separators.
-   * */
+   */
   toHexString(includeDashes = true): string {
     if (includeDashes) {
       return [

src/bson.ts

@@ -70,7 +70,7 @@ let buffer = ByteUtils.allocate(MAXSIZE);
 /**
  * Sets the size of the internal serialization buffer.
  *
- * @param size - The desired size for the internal serialization buffer
+ * @param size - The desired size for the internal serialization buffer in bytes
  * @public
  */
 export function setInternalBufferSize(size: number): void {

src/extended_json.ts

@@ -24,11 +24,19 @@ import { Timestamp } from './timestamp';
 
 /** @public */
 export type EJSONOptions = {
-  /** Output using the Extended JSON v1 spec */
+  /**
+   * Output using the Extended JSON v1 spec
+   * @defaultValue `false`
+   */
   legacy?: boolean;
-  /** Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types */
+  /**
+   * Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types
+   * @defaultValue `false` */
   relaxed?: boolean;
-  /** Enable native bigint support */
+  /**
+   * Enable native bigint support
+   * @defaultValue `false`
+   */
   useBigInt64?: boolean;
 };
 

src/parser/deserializer.ts

@@ -19,21 +19,45 @@ import { validateUtf8 } from '../validate_utf8';
 
 /** @public */
 export interface DeserializeOptions {
-  /** when deserializing a Long will return as a BigInt. */
+  /**
+   * when deserializing a Long return as a BigInt.
+   * @defaultValue `false`
+   */
   useBigInt64?: boolean;
-  /** when deserializing a Long will fit it into a Number if it's smaller than 53 bits. */
+  /**
+   * when deserializing a Long will fit it into a Number if it's smaller than 53 bits.
+   * @defaultValue `true`
+   */
   promoteLongs?: boolean;
-  /** when deserializing a Binary will return it as a node.js Buffer instance. */
+  /**
+   * when deserializing a Binary will return it as a node.js Buffer instance.
+   * @defaultValue `false`
+   */
   promoteBuffers?: boolean;
-  /** when deserializing will promote BSON values to their Node.js closest equivalent types. */
+  /**
+   * when deserializing will promote BSON values to their Node.js closest equivalent types.
+   * @defaultValue `true`
+   */
   promoteValues?: boolean;
-  /** allow to specify if there what fields we wish to return as unserialized raw buffer. */
+  /**
+   * allow to specify if there what fields we wish to return as unserialized raw buffer.
+   * @defaultValue `null`
+   */
   fieldsAsRaw?: Document;
-  /** return BSON regular expressions as BSONRegExp instances. */
+  /**
+   * return BSON regular expressions as BSONRegExp instances.
+   * @defaultValue `false`
+   */
   bsonRegExp?: boolean;
-  /** allows the buffer to be larger than the parsed BSON object. */
+  /**
+   * allows the buffer to be larger than the parsed BSON object.
+   * @defaultValue `false`
+   */
   allowObjectSmallerThanBufferSize?: boolean;
-  /** Offset into buffer to begin reading document from */
+  /**
+   * Offset into buffer to begin reading document from
+   * @defaultValue `0`
+   */
   index?: number;
 
   raw?: boolean;

src/parser/serializer.ts

@@ -16,15 +16,28 @@ import { isAnyArrayBuffer, isDate, isMap, isRegExp, isUint8Array } from './utils
 
 /** @public */
 export interface SerializeOptions {
-  /** the serializer will check if keys are valid. */
+  /**
+   * the serializer will check if keys are valid.
+   * @defaultValue `false`
+   */
   checkKeys?: boolean;
-  /** serialize the javascript functions **(default:false)**. */
+  /**
+   * serialize the javascript functions
+   * @defaultValue `false`
+   */
   serializeFunctions?: boolean;
-  /** serialize will not emit undefined fields **(default:true)** */
+  /**
+   * serialize will not emit undefined fields
+   * note that the driver sets this to `false`
+   * @defaultValue `true`
+   */
   ignoreUndefined?: boolean;
   /** @internal Resize internal buffer */
   minInternalBufferSize?: number;
-  /** the index in the buffer where we wish to start serializing into */
+  /**
+   * the index in the buffer where we wish to start serializing into
+   * @defaultValue `0`
+   */
   index?: number;
 }
 

src/timestamp.ts

@@ -27,7 +27,7 @@ export interface TimestampExtended {
 /**
  * @public
  * @category BSONType
- * */
+ */
 export class Timestamp extends LongWithoutOverridesClass {
   get _bsontype(): 'Timestamp' {
     return 'Timestamp';