Filtering deprecated APIs

[jonwis]

From time to time, we deprecate APIs in Windows. These APIs follow a lifecycle of notification then removal. Occasionally the metadata (like headers or exports) remains behind but the implementation becomes inert (does nothing, returns "not implemented", etc.)

WinRT types have a deprecated attribute on them. Can we do a similar thing for Win32 metadata?

Some feature requests:

• A switch on the projection that suppresses APIs marked deprecated
• An override to the switch so I can hide 99% but bring back the 1% that my app does use
• The deprecated attribute emitted into the metadata so IDEs can highlight these APIs

[mikebattista]

Following on from the discussion at #388 (comment), I would much prefer surfacing things like deprecated attributes than removing APIs from the metadata completely.

What support is there for marking Win32 and COM APIs as deprecated today in the headers? Is this something we could scrape? Or would we have to artificially inject the attribute into the metadata?

[AArnott]

Per #156 we already started using [ObsoleteAttribute] and I suggest we stick with that.

[mikebattista]

Thanks. Looks like that attribute was manually added in the metadata.

@jonwis so would you expect teams that want to benefit from any deprecation support in projections to file a PR in the metadata repo to add this attribute? Or are there changes in the SDK itself that should be made and then scraped?

[kennykerr]

Yes, I would be in favor of using an attribute as that is consistent with WinRT metadata. Language projections can then decide what level of support to provide.

[weltkante]

What support is there for marking Win32 and COM APIs as deprecated today in the headers?

Headers are capable of generating deprecation warnings on usage, I've seen that plenty in the VC runtime headers, but don't know how much it is used in the Windows SDK headers.

Manual deprecation or deprecation from docs makes me a bit worried about "political" deprecation affecting accessibility of APIs to developers, things have been "deprecated" in the past to push the new shiny API. Some of these deprecations seem to have been reverted so I don't really know how bad the current state is, I've stopped trusting the docs marking something as "deprecated". (Some things have been deprecated for over a decade and never went away.)

If its usable from the SDK without warnings it should be usable without warnings from projections.