search

MicrosoftDocs / feedback

📢 docs.microsoft.com site feedback
https://learn.microsoft.com
Creative Commons Attribution 4.0 International
239 stars 160 forks source link

Filter out internal APIs #1854

Open taisbak opened 5 years ago

taisbak commented 5 years ago

In .NET API Browser public as well as internal APIs are all listed.

E.g., when searching for "Include" in Entity Framework Core, a lot of the entries are described as "This API supports the Entity Framework Core infrastructure and is not intended to be used directly from your code. This API may change or be removed in future releases.", which clutters the result unnecessarily.

I suggest a checkbox, like "include internal APIs" to check when I want internal APIs as well. Default should be unchecked.

welcome[bot] commented 5 years ago

Thank you for creating the issue! One of our team members will get back to you shortly with additional information. If this is a product issue, please close this and contact the particular product's support instead (see https://support.microsoft.com/allproducts for the list of support websites).

mairaw commented 5 years ago

We could also filter out from docs certain namespaces. @divega would that make sense for some of these EF Core namespaces like Microsoft.EntityFrameworkCore.Query.Internal?

divega commented 5 years ago

I agree that for the API browser as it is, those "public-internal" APIs just add a lot of clutter in search results and make the experience of browsing the API that customers are much more likely to want to use very clumsy.

It is good that they are discoverable in Intellisense in the IDE and the boilerplate comment that they carry can be seen there to explain the caveats. But finding them in the API browser pages doesn't, in my opinion, add much value.

Given that, I also would like the *.Internal namespaces not to be included in the API browser.

However, I remember from talking to @ajcvickers about this before, that he had a different perspective.

ajcvickers commented 5 years ago

@divega I didn't want to do anything that would make it easier for people to miss that these are internal APIs. But now we have the analyzer I think it's probably fine to remove them from the API browser.

mairaw commented 5 years ago

Do you need help setting that up @divega?

divega commented 5 years ago

Yes, absolutely. And we still need help getting things setup for newer versions of our packages to be published to API browsers. The latest published is EF Core 2.1.

divega commented 5 years ago

@mairaw I got assigned as this issue, but I don't know how to proceed. As per your previous comment, who could help our team with setting up this filter and the publishing of 2.2 and 3.0 APIs?

cc @ajcvickers

divega commented 5 years ago

@smitpatel is going to look into publishing all API reference for EF Core, and can take over this.