search

dotnet / dotnet-api-docs

.NET API reference documentation (.NET 5+, .NET Core, .NET Framework)
https://docs.microsoft.com/dotnet/api/
Other
737 stars 1.57k forks source link

Docs for Channel #6791

Open Regenhardt opened 3 years ago

Regenhardt commented 3 years ago

The documentation for Channel is currently no more than intellisense can tell me (except which framework versions it applies to...), which is not enough for a documentation page: https://docs.microsoft.com/en-us/dotnet/api/system.threading.channels.channel-2

Channel and Channel aren't that important here, since Channel is just for constructing channels and Channel is just Channel<T, T>.

The big one should have at least some description and a simple example. I haven't fully understood the whole blog post yet, but things like

"A channel is basically a data structure that’s used to store produced data for a consumer to retrieve, and an appropriate synchronization to enable that to happen safely, while also enabling appropriate notifications in both directions."

would be a good start for a description. I will update this issue when understanding more of the blog post and getting a better idea about what to put in the docs.

ghost commented 3 years ago

Tagging subscribers to this area: @carlossanlop See info in area-owners.md if you want to be subscribed.

Issue Details
The documentation for Channel is currently no more than intellisense can tell me (except which framework versions it applies to...), which is not enough for a documentation page: https://docs.microsoft.com/en-us/dotnet/api/system.threading.channels.channel-2 Channel and Channel aren't that important here, since Channel is just for constructing channels and Channel is just Channel. The big one should have at least some description and a simple example. I haven't fully understood the whole blog post yet, but things like "A channel is basically a data structure that’s used to store produced data for a consumer to retrieve, and an appropriate synchronization to enable that to happen safely, while also enabling appropriate notifications in both directions." would be a good start for a description. I will update this issue when understanding more of the blog post and getting a better idea about what to put in the docs.
Author: Regenhardt
Assignees: -
Labels: `:watch: Not Triaged`, `Pri3`, `area-System.Threading.Channels`
Milestone: -
ManickaP commented 3 years ago

@adamsitnik @carlossanlop @jozkee

krwq commented 3 years ago

@adamsitnik @carlossanlop @Jozkee might be worth considering to add sample or something to provide people guidance on how to use this library.

adamsitnik commented 3 years ago

@stephentoub do we have any docs for Channels?

stephentoub commented 3 years ago

I've not written any beyond the XML docs (that fed into the API docs) and https://devblogs.microsoft.com/dotnet/an-introduction-to-system-threading-channels/, which is fairly comprehensive (so maybe the request is to just incorporate content from the blog post into the docs?)

krwq commented 3 years ago

My guess link to the article would be fine as well if they are persistent. Incorporating sounds even better though