docs(NODE-3509): Update error documentation #2938

W-A-James · 2021-08-16T21:23:29Z

Description

Update documentation in docs/errors.md to be in parity with src/error.ts

docs/charts/mermaid/MongoAPIError.mmd

docs/errors.md

andymina · 2021-08-17T14:29:06Z

docs/errors.md

+| **MongoGridFSStreamError**    | Thrown when an unexpected state is reached when operating on a GridFS Stream              |
+| **MongoGridFSChunkError**     | Thrown when a malformed or invalid chunk is encountered when reading from a GridFS Stream |
+| **MongoServerSelectionError** | Thrown when the driver fails to select a server to complete an operation                  |
+| **MongoURIError**             | Thrown when a user supplies an incorrect URI to the driver                                |


MongoURIError has been replaced by MongoConnectionStringError so it should be removed.

Have we actually replaced it yet?

We haven't replaced it, but I think it has been removed.

andymina · 2021-08-17T14:30:04Z

docs/errors.md

-
- Attempt to continue reading a cursor after it has reached the end of the batch.
-  - Assert that `MongoCursorExhaustedError` is thrown.
+### `MongoRuntimeError`


If nothing's being tested under MongoRuntimeError, we can remove it from the md.

andymina · 2021-08-17T14:31:01Z

docs/errors.md

    - [`MongoCursorExhaustedError`](#MongoCursorExhaustedError-1)
+    - [`MongoServerClosedError`](#MongoServerClosedError-1)
+    - [`MongoStreamClosedError`](#MongoStreamClosedError-1)
+  - [`MongoRuntimeError`](#MongoRuntimeError-1)


If nothing's being tested under MongoRuntimeError, we can remove it.

andymina

LGTM

emadum

Just some wording/grammar nits, otherwise LGTM 👍

emadum · 2021-08-18T16:51:01Z

docs/errors.md


-This class represents errors which originate in the driver itself or in the user's use of the driver.
-This class should **never** be directly instantiated.
+This class represents errors which originate in the driver itself or in the user's use of the driver. This class should **never** be directly instantiated.


I find the "...or in the user's use of the driver" part unclear, can we rephrase it? Maybe something like "...when the user is using the driver correctly."

emadum · 2021-08-18T16:51:50Z

docs/errors.md

+
+| Error Name                         | Description                                                                                                                                            |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **MongoInvalidArgumentError**      | Thrown when the user supplies malformed, unexpected arguments or failed to provide a required argument or field.                                       |


Suggested change

| **MongoInvalidArgumentError** | Thrown when the user supplies malformed, unexpected arguments or failed to provide a required argument or field. |

| **MongoInvalidArgumentError** | Thrown when the user supplies malformed or unexpected arguments, or failed to provide a required argument or field. |

emadum · 2021-08-18T16:53:46Z

docs/errors.md

+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **MongoInvalidArgumentError**      | Thrown when the user supplies malformed, unexpected arguments or failed to provide a required argument or field.                                       |
+| **MongoCompatibilityError**        | Thrown when a feature that is not enabled or allowed for the current server configuration is used.                                                     |
+| **MongoMissingCredentialsError**   | Thrown when a user fails to provide authentication credentials before attempting to connect to the mongo server.                                       |


Suggested change

| **MongoMissingCredentialsError** | Thrown when a user fails to provide authentication credentials before attempting to connect to the mongo server. |

| **MongoMissingCredentialsError** | Thrown when a user fails to provide authentication credentials before attempting to connect. |

Nit, just for brevity's sake.

emadum · 2021-08-18T16:54:56Z

docs/errors.md

+| **MongoCompatibilityError**        | Thrown when a feature that is not enabled or allowed for the current server configuration is used.                                                     |
+| **MongoMissingCredentialsError**   | Thrown when a user fails to provide authentication credentials before attempting to connect to the mongo server.                                       |
+| **MongoMissingDependencyError**    | Thrown when a required module or dependency is not present.                                                                                            |
+| **MongoExpiredSessionError**       | Thrown when the user attempts to operate on a session that has expired or has been closed.                                                             |


Suggested change

| **MongoExpiredSessionError** | Thrown when the user attempts to operate on a session that has expired or has been closed. |

| **MongoExpiredSessionError** | Thrown when the user attempts to operate on a session that is expired or closed. |

Nit, prefer present imperative tense.

emadum · 2021-08-18T16:55:31Z

docs/errors.md

+| **MongoExpiredSessionError**       | Thrown when the user attempts to operate on a session that has expired or has been closed.                                                             |
+| **MongoTransactionError**          | Thrown when the user makes a mistake in the usage of transactions (e.g.: attempting to commit a transaction with a readPreference other than primary). |
+| **MongoTailableCursorError**       | Thrown when the user calls a function or method that is not supported on a tailable cursor.                                                            |
+| **MongoCursorExhaustedError**      | Thrown when an attempt is made to read from a cursor that has been exhausted.                                                                          |


Suggested change

| **MongoCursorExhaustedError** | Thrown when an attempt is made to read from a cursor that has been exhausted. |

| **MongoCursorExhaustedError** | Thrown when an attempt is made to read from a cursor that is exhausted. |

emadum · 2021-08-18T16:57:08Z

docs/errors.md

+| **MongoCursorInUseError**          | Thrown when the user attempts to add options to an already initialized cursor.                                                                         |
+| **MongoServerClosedError**         | Thrown when an attempt is made to operate on a closed server.                                                                                          |
+| **MongoTopologyClosedError**       | Thrown when an attempt is made to operate on a dropped, or otherwise unavailable, database.                                                            |
+| **MongoNotConnectedError**         | Thrown when the user attempts to operate on the data from a client that has not been connected to a MongoDB server instance.                           |


Suggested change

| **MongoNotConnectedError** | Thrown when the user attempts to operate on the data from a client that has not been connected to a MongoDB server instance. |

| **MongoNotConnectedError** | Thrown when the user attempts to perform operations on a client that is not yet connected. |

emadum · 2021-08-18T16:57:40Z

docs/errors.md

+| **MongoServerClosedError**         | Thrown when an attempt is made to operate on a closed server.                                                                                          |
+| **MongoTopologyClosedError**       | Thrown when an attempt is made to operate on a dropped, or otherwise unavailable, database.                                                            |
+| **MongoNotConnectedError**         | Thrown when the user attempts to operate on the data from a client that has not been connected to a MongoDB server instance.                           |
+| **MongoBatchReExecutionError**     | Thrown when a user attempts to reexecute a batch command when one of the constituent commands has failed.                                              |


Suggested change

| **MongoBatchReExecutionError** | Thrown when a user attempts to reexecute a batch command when one of the constituent commands has failed. |

| **MongoBatchReExecutionError** | Thrown when a user attempts to re-execute a batch command when one of the constituent commands has failed. |

emadum · 2021-08-18T16:58:08Z

docs/errors.md

+| **MongoNotConnectedError**         | Thrown when the user attempts to operate on the data from a client that has not been connected to a MongoDB server instance.                           |
+| **MongoBatchReExecutionError**     | Thrown when a user attempts to reexecute a batch command when one of the constituent commands has failed.                                              |
+| **MongoConnectionStringError**     | Thrown when a user supplies an incorrect URI to the driver.                                                                                            |
+| **MongoConnectionPoolClosedError** | Thrown when a user attempts to operate on a connection pool that has expired or has been closed                                                        |


Suggested change

| **MongoConnectionPoolClosedError** | Thrown when a user attempts to operate on a connection pool that has expired or has been closed |

| **MongoConnectionPoolClosedError** | Thrown when a user attempts to operate on a connection pool that is expired or closed |

nbbeeken

What're the deletions with the SVGs and build_images script? Are we regenerating them after all comments are in?

W-A-James · 2021-08-19T14:27:32Z

@nbbeeken With regards to those deletions, we decided that the majority of the graphs were too bulky, so we exchanged them in favour of tables.

I also now realise that I deleted the first graph that we did intend to keep. Thanks for the heads up.

dariakp

Super minor nit, but we are using periods in the rest of the descriptions, so these are just suggestions for consistency

docs/errors.md

W-A-James added 5 commits August 16, 2021 16:46

docs: Update error documentation

8bcbff7

docs: Update diagrams(wip)

ab554e9

wip: updating docs

9a9dc06

docs: Update testing plan

20b0aa3

docs: Remove unused errors

b9dd6f5

W-A-James requested a review from andymina August 16, 2021 21:23

andymina suggested changes Aug 17, 2021

View reviewed changes

andymina marked this pull request as ready for review August 17, 2021 14:31

andymina added the Primary Review In Review with primary reviewer, not yet ready for team's eyes label Aug 17, 2021

docs: remove charts and update documentation

6953e28

W-A-James requested a review from andymina August 17, 2021 17:27

andymina reviewed Aug 17, 2021

View reviewed changes

andymina approved these changes Aug 17, 2021

View reviewed changes

andymina added Team Review Needs review from team and removed Primary Review In Review with primary reviewer, not yet ready for team's eyes labels Aug 17, 2021

andymina requested review from dariakp, emadum and nbbeeken August 17, 2021 21:12

docs: Remove reference to MongoURIError

ee14487

emadum suggested changes Aug 18, 2021

View reviewed changes

docs: Fix grammar

d65c759

W-A-James requested a review from emadum August 18, 2021 19:06

nbbeeken reviewed Aug 19, 2021

View reviewed changes

W-A-James added 2 commits August 19, 2021 10:38

docs: restore MongoError diagram

c3b7812

docs: Make diagram more readable for dark and light mode

7ab3713

nbbeeken approved these changes Aug 19, 2021

View reviewed changes

docs: Add note about mermaid installation

3b39d6a

dariakp approved these changes Aug 19, 2021

View reviewed changes

docs/errors.md Outdated Show resolved Hide resolved

docs/errors.md Outdated Show resolved Hide resolved

docs: Ensure Error descriptions end with periods

1a3115c

docs: Fix minor error

ef8d0ef

dariakp merged commit 90f28fc into 4.1 Aug 20, 2021

dariakp deleted the NODE-3509/Update-Error-Documentation branch August 20, 2021 18:19

ljhaywar pushed a commit that referenced this pull request Nov 9, 2021

docs(NODE-3509): Update error documentation (#2938)

a837c1d

	\| MongoInvalidArgumentError \| Thrown when the user supplies malformed, unexpected arguments or failed to provide a required argument or field. \|
	\| MongoInvalidArgumentError \| Thrown when the user supplies malformed or unexpected arguments, or failed to provide a required argument or field. \|

	\| MongoMissingCredentialsError \| Thrown when a user fails to provide authentication credentials before attempting to connect to the mongo server. \|
	\| MongoMissingCredentialsError \| Thrown when a user fails to provide authentication credentials before attempting to connect. \|

	\| MongoExpiredSessionError \| Thrown when the user attempts to operate on a session that has expired or has been closed. \|
	\| MongoExpiredSessionError \| Thrown when the user attempts to operate on a session that is expired or closed. \|

	\| MongoCursorExhaustedError \| Thrown when an attempt is made to read from a cursor that has been exhausted. \|
	\| MongoCursorExhaustedError \| Thrown when an attempt is made to read from a cursor that is exhausted. \|

	\| MongoNotConnectedError \| Thrown when the user attempts to operate on the data from a client that has not been connected to a MongoDB server instance. \|
	\| MongoNotConnectedError \| Thrown when the user attempts to perform operations on a client that is not yet connected. \|

	\| MongoBatchReExecutionError \| Thrown when a user attempts to reexecute a batch command when one of the constituent commands has failed. \|
	\| MongoBatchReExecutionError \| Thrown when a user attempts to re-execute a batch command when one of the constituent commands has failed. \|

	\| MongoConnectionPoolClosedError \| Thrown when a user attempts to operate on a connection pool that has expired or has been closed \|
	\| MongoConnectionPoolClosedError \| Thrown when a user attempts to operate on a connection pool that is expired or closed \|

docs(NODE-3509): Update error documentation #2938

docs(NODE-3509): Update error documentation #2938

Uh oh!

Conversation

W-A-James commented Aug 16, 2021

Description

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

andymina Aug 17, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andymina left a comment

Choose a reason for hiding this comment

Uh oh!

emadum left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nbbeeken left a comment

Choose a reason for hiding this comment

Uh oh!

W-A-James commented Aug 19, 2021

Uh oh!

dariakp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

andymina Aug 17, 2021 •

edited

Loading