SWIFT-704 Update async docstrings to reflect error propagation

[kmahar]

Most of this PR is just slightly reformatting docstrings to clarify that futures fail with particular errors now, rather than the errors being thrown.

This excludes the docstrings for cursors and change streams, and methods that return cursors and change streams, as I think you started on those already, but if you think I should pick up any of that while you work on implementing those types let me know.

[patrickfreed]

According to the "Multiline Elements" section of Apple's markup docs, these blocks can begin on the next line down from their delimiters (i.e. - Returns in this case), and they also can be split into multiple paragraphs by inserting single empty lines between sections of text. I personally think its a little clearer if the return content starts on its own line below - Returns, and that the error information is separated into its own paragraph.

e.g.

mongo-swift-driver/Sources/MongoSwift/MongoCursor.swift

Lines 241 to 250 in 763de66

	* - Returns:
	* An `EventLoopFuture<T?>` containing the next `T` in this cursor, an error if one occurred, or `nil` if
	* there was no data.
	*
	* If the future evaluates to an error, it is likely one of the following:
	* - `CommandError` if an error occurs while fetching more results from the server.
	* - `LogicError` if this function is called after the cursor has died.
	* - `LogicError` if this function is called and the session associated with this cursor is inactive.
	* - `DecodingError` if an error occurs decoding the server's response.
	*/

The way this is actually written likely could be improved, but I think the overall format is a bit clearer than a single paragraph. What do you think?

[kmahar]

sgtm, updated all of them

[patrickfreed]

one little suggestion, otherwise LGTM

[patrickfreed]

Could say "On success, the future contains ..." similar to the other docstrings.

[kmahar]

I opted to not do that here because we actually (from the user's perspective) directly return the return value of their closure (which happens to be a future because of how we've specified the type of sessionBody). regardless of whether that succeeds or fails we will directly return it