BsonBinaryWriter._largeByteBuffer is lazily-allocated, but a path
following the allocation doesn't use it. Move the allocation into the
path that makes use of it, to avoid the null-check and potentially the
allocation.
XML documentation comments for JsonReader, JsonWriter and derived
classes often mention "underlying streams". In most cases however,
these types don't operate directly on Streams, but through other types
such as TextReader and TextWriter.
This commit changes these comments to reflect more accurately what
kind of objects the various JSON reader / writer classes operate on.
Additionally the effect of JsonReader.CloseInput and JsonWriter.Close-
Output is made more explicit in the comments for the Close methods.
* Add references to types where they are missing.
* Fix incorrect references to closed generic types.
* Convert member ID strings to proper references where they can be
converted without breaking the build. The remaining member ID
strings usually mean that the comment would have to be rephrased
for at least one build target / platform.
* Drop namespaces from type names where they are unnecessary.
* Fix the odd typo and add additional <c> markup in a few places.
* Simple stuff: typos and missing punctuation and line breaks.
* Sometimes, two method overloads have quite different documentation.
Rephrase these to make them more similar.
* Minor rephrasings like in a previous commit (e.g. "...how output
should be formatted", "initializes a new instance of...").
* Obvious incorrect type references in comments. These appear mostly
in `Utilities/LinqBridge.cs` (nullable vs non-nullable).
* Remove factually incorrect statement about exceptions thrown.
* Remove comments for explicitly implemented interface methods.
* Explicitly implemented interfaces don't need comments.
* Protected constructors of abstract classes should be documented
like Microsoft does on MSDN.
* Replace term "Common Language Runtime (CLR) type" with ".NET type".
This fixes several minor issues in the code's documentation comments,
such as spelling errors, missing punctuation and references to other
code elements, and a few other small inconsistencies.
If the JSON contained empty object "{}" for a byte[] property, the `JsonReader` ended up trying to read the object content despite the fact that the content didn't exist. This caused a null reference exception.
The fix ensures the value exists before trying to read it. If the value doesn't exist, the execution ends up in "Unexpected token" exception with way more informative error message.
Jon Hanna