search

dotnet / dotnet-api-docs

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

Missing xmldocs for Microsoft.Extensions.Caching.Memory CacheExtensions #6871

Open ericsampson opened 3 years ago

ericsampson commented 3 years ago

There's no xmldocs for MemoryCacheExtensions, which makes the online API browser docs and intellisense of little use.

Also, these docs should really include a mention that the GetOrCreate/GetOrCreateAsync factories is not blocked for re-entrancy unless the programmer implements that themselves (easiest way is to use Lazy)

For an example of good documentation of the same topic for a different class, check out the Remarks for ConcurrentDictionary AddOrUpdate

As can be seen in this GH issue, and from my own experience, people often get tripped up by this fact.

Thanks!

ghost commented 3 years ago

Tagging subscribers to this area: @eerhardt, @maryamariyan, @michaelgsharp See info in area-owners.md if you want to be subscribed.

Issue Details
There's no xmldocs for [MemoryCacheExtensions](https://github.com/aspnet/Caching/blob/master/src/Microsoft.Extensions.Caching.Abstractions/MemoryCacheExtensions.cs), which makes the online API browser docs and intellisense of little use. Also, these docs should really include a mention that the `GetOrCreate`/`GetOrCreateAsync` factories is not blocked for re-entrancy unless the programmer implements that themselves (easiest way is to use `Lazy`) For an example of good documentation of the same topic for a different class, check out the Remarks for [ConcurrentDictionary AddOrUpdate](https://docs.microsoft.com/en-us/dotnet/api/system.collections.concurrent.concurrentdictionary-2.addorupdate?view=net-5.0) As can be seen in [this GH issue](https://github.com/dotnet/runtime/issues/36499), and from my own experience, people often get tripped up by this fact.
Author: ericsampson
Assignees: -
Labels: `area-Extensions-Caching`, `untriaged`
Milestone: -
dotnet-issue-labeler[bot] commented 3 years ago

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

ghost commented 3 years ago

Tagging subscribers to this area: @eerhardt, @maryamariyan, @michaelgsharp See info in area-owners.md if you want to be subscribed.

Issue Details
There's no xmldocs for [MemoryCacheExtensions](https://github.com/aspnet/Caching/blob/master/src/Microsoft.Extensions.Caching.Abstractions/MemoryCacheExtensions.cs), which makes the online API browser docs and intellisense of little use. Also, these docs should really include a mention that the `GetOrCreate`/`GetOrCreateAsync` factories is not blocked for re-entrancy unless the programmer implements that themselves (easiest way is to use `Lazy`) For an example of good documentation of the same topic for a different class, check out the Remarks for [ConcurrentDictionary AddOrUpdate](https://docs.microsoft.com/en-us/dotnet/api/system.collections.concurrent.concurrentdictionary-2.addorupdate?view=net-5.0) As can be seen in [this GH issue](https://github.com/dotnet/runtime/issues/36499), and from my own experience, people often get tripped up by this fact. Thanks!
Author: ericsampson
Assignees: -
Labels: `:watch: Not Triaged`, `Pri3`, `area-Extensions-Caching`
Milestone: -