From 3252fb859711cc74c804bb3342f036e7f631cb94 Mon Sep 17 00:00:00 2001 From: Tristan Labelle Date: Thu, 29 Aug 2024 15:23:43 +0200 Subject: [PATCH] Add readmes and more doc comments (#246) --- Package.swift | 2 +- Support/Readme.md | 1 + .../Sources/WindowsRuntime/ProjectedTypes/Core/Readme.md | 1 + .../ProjectedTypes/WindowsFoundation/Readme.md | 8 ++++++++ .../{DateTime.swift => WindowsFoundation_DateTime.swift} | 0 ...Value.swift => WindowsFoundation_IPropertyValue.swift} | 0 ...Reference.swift => WindowsFoundation_IReference.swift} | 4 ++++ ...rray.swift => WindowsFoundation_IReferenceArray.swift} | 0 ...ringable.swift => WindowsFoundation_IStringable.swift} | 0 .../{Point.swift => WindowsFoundation_Point.swift} | 0 ...rtyType.swift => WindowsFoundation_PropertyType.swift} | 0 .../{Rect.swift => WindowsFoundation_Rect.swift} | 0 .../{Size.swift => WindowsFoundation_Size.swift} | 0 .../{TimeSpan.swift => WindowsFoundation_TimeSpan.swift} | 0 14 files changed, 15 insertions(+), 1 deletion(-) create mode 100644 Support/Readme.md create mode 100644 Support/Sources/WindowsRuntime/ProjectedTypes/Core/Readme.md create mode 100644 Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/Readme.md rename Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/{DateTime.swift => WindowsFoundation_DateTime.swift} (100%) rename Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/{IPropertyValue.swift => WindowsFoundation_IPropertyValue.swift} (100%) rename Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/{IReference.swift => WindowsFoundation_IReference.swift} (94%) rename Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/{IReferenceArray.swift => WindowsFoundation_IReferenceArray.swift} (100%) rename Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/{IStringable.swift => WindowsFoundation_IStringable.swift} (100%) rename Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/{Point.swift => WindowsFoundation_Point.swift} (100%) rename Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/{PropertyType.swift => WindowsFoundation_PropertyType.swift} (100%) rename Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/{Rect.swift => WindowsFoundation_Rect.swift} (100%) rename Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/{Size.swift => WindowsFoundation_Size.swift} (100%) rename Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/{TimeSpan.swift => WindowsFoundation_TimeSpan.swift} (100%) diff --git a/Package.swift b/Package.swift index d8a05a49..ddda3b61 100644 --- a/Package.swift +++ b/Package.swift @@ -35,7 +35,7 @@ let package = Package( name: "WindowsRuntime", dependencies: ["COM", "WindowsRuntime_ABI", "InternalABI"], path: "Support/Sources/WindowsRuntime", - exclude: ["CMakeLists.txt"]), + exclude: ["CMakeLists.txt", "Readme.md"]), .testTarget( name: "Tests", dependencies: ["COM", "WindowsRuntime"], diff --git a/Support/Readme.md b/Support/Readme.md new file mode 100644 index 00000000..9767a328 --- /dev/null +++ b/Support/Readme.md @@ -0,0 +1 @@ +Provides the infrastructure for COM and Windows Runtime projections, which generated code depends on. \ No newline at end of file diff --git a/Support/Sources/WindowsRuntime/ProjectedTypes/Core/Readme.md b/Support/Sources/WindowsRuntime/ProjectedTypes/Core/Readme.md new file mode 100644 index 00000000..ff714b35 --- /dev/null +++ b/Support/Sources/WindowsRuntime/ProjectedTypes/Core/Readme.md @@ -0,0 +1 @@ +Defines core WinRT types which only have definitions in C++ headers, not in Windows Metadata files. \ No newline at end of file diff --git a/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/Readme.md b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/Readme.md new file mode 100644 index 00000000..d5419d39 --- /dev/null +++ b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/Readme.md @@ -0,0 +1,8 @@ +This directory defines core types from the `Windows.Foundation` namespace (`Windows.Foundation.WindowsFoundationContract` assembly), +which are required by WinRT support code and hence cannot be code generated. + +`IReference` and `IReferenceArray` need built-in support because we can express them through a single virtual table, independent of T, which allows implementing boxing for arbitrary primitive types, value types and delegate types. + +`IPropertyValue` and `PropertyType` have nothing special and could be code generated, if it were not that the former is a base interface for `IReference` and `IReferenceArray`. `IPropertyValue` also refers to `DateTime`/`TimeSpan` and `Point`/`Size`/`Rect`, preventing them from being code generated. + +`IStringable` has built-in support so we can automatically implement it in terms of `CustomStringConvertible`. \ No newline at end of file diff --git a/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/DateTime.swift b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_DateTime.swift similarity index 100% rename from Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/DateTime.swift rename to Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_DateTime.swift diff --git a/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/IPropertyValue.swift b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_IPropertyValue.swift similarity index 100% rename from Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/IPropertyValue.swift rename to Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_IPropertyValue.swift diff --git a/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/IReference.swift b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_IReference.swift similarity index 94% rename from Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/IReference.swift rename to Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_IReference.swift index 1105c791..1a904fb0 100644 --- a/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/IReference.swift +++ b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_IReference.swift @@ -1,4 +1,8 @@ /// Enables arbitrary enumerations, structures, and delegate types to be used as property values. +/// +/// This interface has two uses in WinRT: +/// - Boxing primitives, value types and delegates to IInspectable. +/// - Providing a representation for nullable primitives, value types and delegates (since reference types can be null). public typealias WindowsFoundation_IReference = any WindowsFoundation_IReferenceProtocol /// Allows nongeneric uses of the IReference protocol. diff --git a/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/IReferenceArray.swift b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_IReferenceArray.swift similarity index 100% rename from Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/IReferenceArray.swift rename to Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_IReferenceArray.swift diff --git a/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/IStringable.swift b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_IStringable.swift similarity index 100% rename from Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/IStringable.swift rename to Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_IStringable.swift diff --git a/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/Point.swift b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_Point.swift similarity index 100% rename from Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/Point.swift rename to Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_Point.swift diff --git a/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/PropertyType.swift b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_PropertyType.swift similarity index 100% rename from Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/PropertyType.swift rename to Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_PropertyType.swift diff --git a/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/Rect.swift b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_Rect.swift similarity index 100% rename from Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/Rect.swift rename to Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_Rect.swift diff --git a/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/Size.swift b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_Size.swift similarity index 100% rename from Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/Size.swift rename to Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_Size.swift diff --git a/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/TimeSpan.swift b/Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_TimeSpan.swift similarity index 100% rename from Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/TimeSpan.swift rename to Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/WindowsFoundation_TimeSpan.swift