NegotiateStream - update documentation

[aik-jahoda]

Summary

Collect all changes from #3916 related to NegotiateStream

[gewarren]

The code sample isn't rendering in the preview. Also, I don't see a snippet4 in the file:

https://github.com/dotnet/dotnet-api-docs/blob/f8c76428f485dbc09e9c4fa8b30877fc44ac10d8/samples/snippets/csharp/VS_Snippets_Remoting/NclNegoasyncClient/CS/client.cs

[aik-jahoda]

this section in the file is referred from multiple places. I will take a look if it renders correctly on other places too.

[aik-jahoda]

there is quite inconsistency in the examples:
C++ and VB are same and uses BexinXXX, EndXXX methods
C# uses XXXAsync methods.

NclNegoasyncClient.cpp
client.cs
client.vb

It implies that in the BexinXXX method docs we show C# example however not for the specific api. On other side C++ and VB are accurate.

I'm not sure how to handle it as there is several options:

1. Create BexinXXX, EndXXX variant for C# async methods
   1. it demonstrate legacy approach
   2. we still need Task based async examples - code duplication
2. Let it like it is and remove C# example from BexinXXX, EndXXX
   1. It sounds strange to me as C# is main .net language and we would offer examples in other languages only
3. Rework VB + C++ to not use BexinXXX, EndXXX but Task based async methods
   1. It would unify the examples
   2. it would require remove examples from BexinXXX, EndXXX docs and move it to Task based async methods

Example of mismatched examples:
https://docs.microsoft.com/en-us/dotnet/api/system.net.security.negotiatestream.beginwrite?view=netcore-3.1

The C# example doesn't contain the related api.

@karelz, any thought?

[aik-jahoda]

I removed the example completely. There is follow up ticket: #4390