Add readmes and more doc comments (#246)

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"],

Support/Readme.md

@@ -0,0 +1 @@
+Provides the infrastructure for COM and Windows Runtime projections, which generated code depends on.

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.

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<T>` and `IReferenceArray<T>` 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<T>` and `IReferenceArray<T>`. `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`.

Support/Sources/WindowsRuntime/ProjectedTypes/WindowsFoundation/IReference.swift → 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<T> = any WindowsFoundation_IReferenceProtocol<T>
 
 /// Allows nongeneric uses of the IReference protocol.