Skip to content

User/chriwall/deprecated - #302

Open
Dreynor87 wants to merge 6 commits into
mainfrom
user/chriwall/deprecated
Open

Dreynor87 wants to merge 6 commits into
mainfrom
user/chriwall/deprecated

Conversation

@Dreynor87

Copy link
Copy Markdown

This implements the deprecated attribute as described here: https://learn.microsoft.com/en-us/uwp/api/windows.foundation.metadata.deprecatedattribute?view=winrt-26100
Along with the DeprecationType enum as described here: https://learn.microsoft.com/en-us/uwp/api/windows.foundation.metadata.deprecationtype?view=winrt-26100

Fixes: WinRT Deprecation, that right now does not do anything.

Chris Wall (WIN SDE) and others added 6 commits March 2, 2026 13:23
When -deprecatedincluded is used, emit /** @deprecated message */ JSDoc
annotations in generated .d.ts files for:
- Deprecated types (classes, interfaces, enums, delegates)
- Deprecated enum values (with parent type propagation)
- Deprecated methods and constructors
- Deprecated properties and fields
- Deprecated event listeners

Added get_deprecated_message() helper to MetadataHelpers.h to extract
the deprecation message string from DeprecatedAttribute metadata.

Note: Uses ^@ escape for @ in TextWriter format strings to avoid
TextWriter interpreting @ as a format placeholder.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- tests/TestArtifacts/verify_deprecated.ps1: Runs rnwinrt against system
  WinMD and verifies @deprecated JSDoc annotations on deprecated types,
  enums, methods, and properties (10/10 checks pass)
- docs/deprecated.md: Documents the deprecated annotation feature

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
When DeprecatedAttribute has DeprecationType.Remove (arg[1]==1), the type
or member is completely hidden from the generated TypeScript declarations.
Added is_removed() helper to MetadataHelpers.h. Checks applied to delegates,
enums, enum fields, classes/interfaces, fields, properties, methods, and
event listeners in TypescriptWriter.h.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- verify_removed.ps1 validates deprecated/removed support:
  * DeprecationType enum has both deprecate(0) and remove(1)
  * is_removed(), is_deprecated(), get_deprecated_message() helpers exist
  * TypescriptWriter has is_removed() checks and WriteDeprecatedJsdoc()
  * Generated .d.ts artifacts have content

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Bug fixes in TypescriptWriter.h:
- Property deprecation: check is_removed(getter) instead of
  is_removed(prop), since MIDL places DeprecatedAttribute on the
  getter method, not the Property metadata row
- Guard all is_removed() checks with !settings.IncludeDeprecated
  so that -deprecatedincluded mode shows removed items with
  @deprecated annotations (previously still filtered them out)

verify_removed.ps1: Rewrote with WinMD-based generation tests (40 checks)
- Mode 1 (no deprecated): Verifies removed types, methods, properties,
  static properties, events, and constructors are excluded
- Mode 2 (deprecated included): Verifies all items present with
  @deprecated JSDoc annotations

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…on tests

- Settings.cpp: unconditional is_removed() in is_type_allowed()
- TypescriptWriter.h: change 9 conditional is_removed() checks to unconditional
  (removed items are always filtered, even with -deprecatedincluded)
- ReactFileGenerator.cpp: is_removed() guards in class iteration loops
- verify_removed.ps1: 47 regression tests for source guards, TS output, C++ bridge

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Removal filtering remains inconsistent between native and TypeScript projections, and annotation handling and verification scripts have unresolved correctness issues.

10 open issues
What changed in this PR

This PR adds WinRT deprecation handling to the projection generator, including TypeScript annotations and filtering for APIs marked as removed.

Changes:

  • Reads deprecation messages and removal metadata, and adds filtering and JSDoc generation.
  • Adds verification scripts and usage documentation.
  • Checks in generated PlayTo projections and runtime support code.
File Description
tests/​verify_removed.ps1 Verifies removed API filtering and generated output.
tests/​TestArtifacts/​verify_deprecated.ps1 Checks deprecation annotations using PlayTo metadata.
rnwinrt/​Windows.Media.PlayTo.g.h Adds PlayTo projection declarations.
rnwinrt/​Windows.Media.PlayTo.g.cpp Adds PlayTo native bridge mappings.
rnwinrt/​Windows.Media.g.h Declares the Media namespace projection.
rnwinrt/​Windows.Media.g.cpp Connects Media to the PlayTo projection.
rnwinrt/​Windows.g.h Declares the Windows namespace projection.
rnwinrt/​Windows.g.cpp Connects Windows to the Media projection.
rnwinrt/​rnwinrt/​TypescriptWriter.h Adds deprecation annotations and removal checks.
rnwinrt/​rnwinrt/​Settings.cpp Excludes removed types regardless of inclusion flags.
rnwinrt/​rnwinrt/​react/​ReactFileGenerator.cpp Adds removed-class generation guards.
rnwinrt/​rnwinrt/​MetadataHelpers.h Adds deprecation message and removal helpers.
rnwinrt/​Projections.g.cpp Registers generated namespaces and interfaces.
rnwinrt/​ProjectedValueConverters.g.h Adds a generated converter header stub.
rnwinrt/​base.cpp Adds projection runtime support implementation.
docs/​deprecated.md Documents annotations, usage, and verification.

Review effort: Balanced

if (!message.empty())
{
textWriter.WriteIndentedLine("/** ^@deprecated "sv);
textWriter.Write(message);
Comment on lines +101 to +114
auto attr = winmd::reader::get_attribute(row, metadata_namespace, "DeprecatedAttribute"sv);
if (attr)
{
auto sig = attr.Value();
auto const& fixedArgs = sig.FixedArgs();
if (fixedArgs.size() >= 2)
{
// DeprecationType enum: Deprecate=0, Remove=1
auto const& elemSig = std::get<winmd::reader::ElemSig>(fixedArgs[1].value);
auto const& enumVal = std::get<winmd::reader::ElemSig::EnumValue>(elemSig.value);
return std::visit([](auto v) -> bool { return static_cast<int32_t>(v) == 1; }, enumVal.value);
}
}
return false;
Comment on lines +124 to +126
if (is_removed(field))
{
continue;
Comment on lines +298 to +307
// MIDL places DeprecatedAttribute on getter method, not Property row
auto getter = prop.MethodSemantic().first.Method();
if (is_removed(getter))
{
continue;
}
if (is_deprecated(getter))
{
WriteDeprecatedJsdoc(textWriter, get_deprecated_message(getter));
}
Comment on lines +332 to +333
else if (is_removed(method))
continue;
// Event Listeners:
for (auto&& method : eventListeners)
{
if (is_removed(method))
Comment on lines +358 to +360
if (is_deprecated(method))
{
WriteDeprecatedJsdoc(textWriter, get_deprecated_message(method));

try {
Write-Host "`nGenerating TypeScript for Windows.Media.PlayTo (deprecated namespace)..."
& $rnwinrtPath -input local -include Windows.Media.PlayTo -tsoutput $outDir -deprecatedincluded

# 9. Non-deprecated types should NOT have @deprecated
# CurrentTimeChangeRequestedEventArgs is NOT deprecated
$nonDeprecatedSection = $content | Select-String -Pattern 'class CurrentTimeChangeRequestedEventArgs' -Context 2
Comment thread tests/verify_removed.ps1
Comment on lines +147 to +150
& $rnwinrtPath -input $WinMDPath -input local -include DeprecationTest -include Windows.Foundation -output $cppOutDir 2>&1 | Out-Null

$gHFile = Join-Path $cppOutDir "rnwinrt\DeprecationTest.g.h"
$gCppFile = Join-Path $cppOutDir "rnwinrt\DeprecationTest.g.cpp"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants