dotnet / dotnet/dotnet-api-docs

Rewrite socket documentation entirely, leave no stone unturned

Aperta
#7,609 7 commenti 5 reazioni 0 assegnatari Vedi su GitHub
area-System.Net.Sockets Pri3 untriaged
Lingua principale
C#
Stelle
950
Fork
1.7k
Merge medio
2g 19h
PR unite (30g)
52

Descrizione

The documentation for socket-based code is not in a good state. The code samples are actually great: They demonstrate all the ways you can misuse sockets 🙃

@geoffkizer has written an [analysis of one particular gem](https://github.com/dotnet/runtime/issues/63154). I know from experience that there are many, many other snippets of similar quality. One can only imagine how many novices have been mislead by that documentation. As an extensive Stack Overflow contributor, I have seen a constant stream of confused people who sometimes explicitly point at the official documentation as the source of their misguided patterns.

As an example, let's look at how the [documentation for `TcpClient.DataAvailable`](https://docs.microsoft.com/en-us/dotnet/api/system.net.sockets.networkstream.dataavailable?view=net-6.0) demonstrates its misuse very nicely. And then, let's compare it to the suffering that it has caused: Searching the web for "site:stackoverflow.com tcpclient dataavailable" returns about 1000 results. Stack Overflow is a great way to see what "grassroots" problems there are with a certain technology.

Another example: [Socket.BeginConnect should not block using an event (what's the point?)](https://docs.microsoft.com/en-us/dotnet/api/system.net.sockets.socket.beginconnect?view=net-6.0#system-net-sockets-socket-beginconnect(system-net-ipaddress-system-int32-system-asynccallback-system-object)). I have seen people use this exact pattern, and I know where it comes from.

Reworking one or two of those samples is a drop in the bucket. The entire socket documentation needs to be inspected and revised.

I don't think it's such a good idea to put small sample code snippets in many locations (as it is done now). This just spreads the documentation out over many pages. Socket programming requires an understanding of fundamental concepts. For example, the concept of a byte stream is a general idea. This idea is concretely used in many socket APIs. The concept should be explained once and then be referenced. Another concept is that you can't know if a TCP connection is still viable. No API can exist that tells whether a socket is actually connected in a practical sense.

Most information should be laid out on a few large pages that comprehensively write up a certain topic. Individual APIs can then link to sections of those larger pages for guidance. What good is sample code for a `Socket.ReadAsync` call when you don't understand how sockets work in general? And we don't want to duplicate the proper usage guidance on dozens of pages for each API that directly or indirectly reads from a socket.

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Iniziare esaminando le pagine della documentazione dell’API di TcpClient.DataAvailable e Socket.BeginConnect, insieme all’analisi collegata nell’issue 63154. Fare un inventario degli esempi di socket e identificare i modelli e i concetti fuorvianti che necessitano di una guida consolidata. Per considerarlo completato sarebbe necessaria una riscrittura definita e completa, ma questo issue non specifica le pagine né un ambito attuabile.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
csharp
Ambito
documentation, networking
Tipo di issue
Documentazione
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Ferma
Chiarezza
Da chiarire
Idoneità per principianti
25/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.