[CSHARP-1428] InsertOneAsync use and documentation are incosistent Created: 01/Oct/15  Updated: 02/Oct/15  Resolved: 02/Oct/15

Status: Closed
Project: C# Driver
Component/s: API
Affects Version/s: 2.0, 2.0.1
Fix Version/s: None

Type: Improvement Priority: Minor - P4
Reporter: Paul Faria Assignee: Unassigned
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Backwards Compatibility: Major Change

 Description   

The implementation of the InsertOneAsync is not consistent with its documentation. The method signature of InsertOneAsync is listed as Task InsertOneAsync(..., and the documentation (both in the code and online) states:

Return Value
Type: Task
The result of the insert operation.

This is inconsistent with the previous version of the API as well as with the original mongo api, which both return a WriteResult (see this section of the tutorial). The importance of the WriteResult is that it includes an error message that can be logged to help diagnose the issue. With just the Task, there is not enough information to help determine why the insert had failed.



 Comments   
Comment by Craig Wilson [ 02/Oct/15 ]

We should probably have better linking .

Thanks for the feedback. I'm going to close this ticket. Feel free to re-open or comment further if necessary.

Craig

Comment by Paul Faria [ 02/Oct/15 ]

Hi Craig,

Yes, this does. I apologize for the confusion on my part. Those didn't come up during my research.

Comment by Craig Wilson [ 02/Oct/15 ]

Hi Paul,

I see you are looking at the quickstart guide on our mongodb docs site. While this is good for getting up and running, more comprehensive documentation is here. For instance, there is a whole document on error handling with a section on write errors.

Does this satisfy your documentation needs?

Craig

Comment by Paul Faria [ 02/Oct/15 ]

Hi Craig,

I've talked it over with some members of my team, and we understand now why you removed the result from the return. I think the documentation surrounding this should be a little clearer, especially in the Getting Started Guid where it states, "The [InsertOneAsync] method does not return a result" (This conflicts with the documentation above). The text in this blog post about the release also states, "InsertOneAsync returns a Task with no result value. When the insert is completed the Task will be in either a completed or faulted state depending on whether the insert was successful."

I think it would be very useful to have documentation that showed recommended ways of handling the errors. It would clear up a lot of confusion around this, especially since placing try/catch around Task's doesn't behave like a normal try/catch (due to everything being wrapped in an AggregationException).

Comment by Craig Wilson [ 01/Oct/15 ]

Hi Paul,

The return value in the previous version of the API was problematic. It would never actually contain errors because any errors would get thrown as an exception.

In the case of InsertOneAsync, there is literally nothing to tell. Exceptions will be thrown for errors, and when there is no error, there is nothing to put in a result object. We could create an InsertOneResult class, but it would contain nothing.

Thoughts?

Generated at Wed Feb 07 21:39:34 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.