Add API docs for System.Data.DataReaderExtensions

[divega]

cc @carlossanlop, @mairaw, @roji, @ajcvickers

Made a few fixes on the DbDataReader API docs:

• Removed unnecessary, redundant wording
• Removed SqlClient-specific content
• Fixed incorrect descriptions

[divega]

Review these boilerplate remarks.

[carlossanlop]

Thanks for making this change, Diego. I'm adding Maira and Ron for language review.

[rpetrusha]

I've left a number of comments and suggestions for you to consider, @divega. Some of he suggested changes also apply to other occurences in the two files.

[divega]

Thanks @rpetrusha for all the feedback. I have incorporated most of your suggestions.

[divega]

I think I prefer to mention that returns the type (maybe say the .NET type to differentiate from the database type) and leave out the word object. I will make that change, you can let me know later how it looks like for you.

[divega]

@rpetrusha, @carlossanlop, @mairaw any thought on how useful is having a link to a related article is in here? In the DbDataReader file, the existing link is always the same, an overview of ADO.NET: ~/docs/framework/data/adonet/ado-net-overview.md

[rpetrusha]

Since it's always the same, @divega, it doesn't seem very useful. I think it's OK to remove it.

Also, did you mean to mark this PR as a draft?

[rpetrusha]

The build report was showing three broken links, so I've fixed them.

[divega]

Also, did you mean to mark this PR as a draft?

Yea, it was the intention initially, but now I think it is getting closer to ready.

[divega]

I have done another pass in which I:

• Made exceptions thrown more consistent
• Removed async default implementation details from summary
• Improved returned value description for more async methods
• Created semi-standard remark for async methods that I expect to use a lot in my next PR, so I would grateful if I can get some feedback. This is the most complete version (in reality not all sentences apply to all methods):

Remarks

This asynchronous method is only needed to avoid blocking the calling thread when the reader is created in sequential mode.

If sequential mode isn't specified, all column values should become available in memory each time ReadAsync completes, and calling the synchronous version of the method shouldn't block the calling thread.

The default implementation of this asynchronous method invokes its synchronous counterpart and returns a completed Task, potentially blocking the calling thread. The default implementation also returns a cancelled task if passed an already cancelled cancellation token.

Data providers that support asynchronous programming should override the default inmplementation using asynchronous I/O operations.

This method accepts a cancellation token that can be used to request the operation to be cancelled early. Implementations may ignore this request.

Other methods and properties of the DbDataReader object should not be invoked while the returned Task is not yet completed.

[rpetrusha]

This looks good, @divega. Thanks for making the additional changes. I'll merge your PR now.