StreamWriter constructor documentation mismatch with implementation

[rameel]

There is an inconsistency between the documentation and the actual implementation of the StreamWriter constructors. The documentation states that passing null to the Encoding parameter in some constructors, except the main one, will result in an exception being thrown. However, all these constructors pass the Encoding argument to the main constructor, which allows null.

public StreamWriter(Stream stream, Encoding encoding)
    : this(stream, encoding, DefaultBufferSize, false);

public StreamWriter(Stream stream, Encoding encoding, int bufferSize)
    : this(stream, encoding, bufferSize, false);

public StreamWriter(Stream stream, Encoding? encoding = null, int bufferSize = -1, bool leaveOpen = false);

StreamWriter.cs
Documentation

Suggested Fix:

• Mark the Encoding parameter as nullable in these constructors.
• Update the documentation.

- public StreamWriter(Stream stream, Encoding encoding);
- public StreamWriter(Stream stream, Encoding encoding, int bufferSize);
+ public StreamWriter(Stream stream, Encoding? encoding);
+ public StreamWriter(Stream stream, Encoding? encoding, int bufferSize);

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-io
See info in area-owners.md if you want to be subscribed.

[DaZombieKiller]

According to the reference sources, all of the constructors appear to throw for a null encoding value in .NET Framework. I suppose this might just be a case where the behavior changed in .NET Core and some of the overloads got missed when updating the docs.

[KalleOlaviNiemitalo]

The behavior was changed in dotnet/coreclr#24056 to fix #17157. Before that, the StreamReader and StreamWriter constructors would have thrown ArgumentNullException if encoding == null. #2376 is also related.