Closed carlossanlop closed 4 years ago
Many of these APIs no longer exist. For instance, EnumBuilder.ContainsGenericParameters
only existed in .NET Core 1.0 and .NET Core 1.1 - both of which are EOL. It was never in any version of .NET Framework or .NET Standard.
While docing these we should investigate whether we should focus our efforts on documenting APIs that exist in supported releases / standards only. Otherwise I imagine we could end up sinking a lot of time into this for very little payoff.
only existed in .NET Core 1.0 and .NET Core 1.1 - both of which are EOL
@GrabYourPitchforks so they were shipped in 1.0 and 1.1, correct? It's my understanding that APIs are never removed, which means they can still be used by users of 2.x, 3.x and 5.0. So they need to be documented.
Is my understanding correct or did I miss something?
@carlossanlop @GrabYourPitchforks I'm checking internally what, if any, compliance issues would apply to these APIs.
@carlossanlop Some of these APIs do not exist in .NET Core 2.0+. In many cases they got removed in favor of leaving only the base class implementation.
For instance, TypeBuilder
, TypeInfo
, and EnumBuilder
all subclass Type
. Type
defines a virtual method ContainsGenericParameters
, and all three of those subclassed types overrode the method. But in .NET Core 2.0, all of these overrides were removed, so all callers use the base method declaration Type.ContainsGenericParameters
, which is already documented.
Some of these APIs do not exist in .NET Core 2.0+
Interesting. So we do have exceptions.
The report with undoc APIs generated by the Docs build system does not indicate in any way if an API has been removed. I would expect area owners to help find out these special cases.
in .NET Core 2.0, all of these overrides were removed, so all callers use the base method declaration Type.ContainsGenericParameters, which is already documented.
We don't have a mechanism to inherit documentation from base classes, unfortunately.
@mimisasouvanh @joelmartinez should we have a mechanism that fills the "To be added." strings of APIs that inherit from base classes, automatically pre-filled with the parent's documentation instead? See: dotnet-api-docs/xml/System.Reflection.Emit/EnumBuilder.xml#L280-L306
Wouldn't the report just have earlier versions and not later versions when the API gets dropped? That would be a good indication that the API was removed.
I think there is a request for mdoc to support the inheritdoc tag.
What prompted my initial question was that Steve and I were triaging issues, and we're trying to figure out how to get through some of the load of this. We want to focus on .NET Core 2.0+ APIs since that should involve the least amount of throwaway work and should benefit the largest percentage of our user base.
Yeah, like @mairaw mentioned, some variation of a response/support for this has been on the request list for a while ... there's a few different ways the problem could be approached (inheritdoc
being one of them).
I'd recommend you work with @mimisasouvanh to get a feature cycled into the priority list ... that way we can review all the cases this affects (interface implementations, overridden members, etc) and pick a solution that has the most impact :)
Probably the best option is to download the undocumented API report and apply some filters. You'd be able to see which ones are also supported on later versions. Ping me if you need any help.
@GrabYourPitchforks @steveharter you can use the DocsPortingTool to quickly and easily port the EII documentation strings. There are instructions and an example in the README. Let me know if you have any questions about it.
Closing this for 5.0. Please re-open if appropriate based upon a new report, or when there is an inheritdoc
feature and System.Reflection needs to update existing doc to leverage that.
@steveharter @GrabYourPitchforks
Here are the undocumented API from
System.Reflection
. They were introduced in 1.x. There's some debt from the 2.x effort. We are asking all area owners to report back their plan/commitment for their undocumented APIs in order to tackle 33% of the APIs in the next month. Can you please help us with that?For more information on the plan, see: #3904
Total: 395. Note: The table has 3 really long columns.