Add better xml docs

src/Microsoft.Windows.CsWin32/Generator.cs

@@ -54,6 +54,13 @@ public class Generator : IDisposable
         { "POINTF", ParseTypeName("global::System.Drawing.PointF") },
     };
 
+    /// <summary>
+    /// A map of .NET interop structs to use, keyed by the native structs that should <em>not</em> be generated <em>when marshaling is enabled.</em>
+    /// That is, these interop types should only be generated when marshaling is disabled.
+    /// </summary>
+    /// <devremarks>
+    /// When adding to this dictionary, consider also adding to <see cref="BannedAPIsWithMarshaling"/>.
+    /// </devremarks>
     internal static readonly Dictionary<string, TypeSyntax> AdditionalBclInteropStructsMarshaled = new Dictionary<string, TypeSyntax>(StringComparer.Ordinal)
     {
         { nameof(System.Runtime.InteropServices.ComTypes.IDataObject), ParseTypeName("global::System.Runtime.InteropServices.ComTypes.IDataObject") },
@@ -409,6 +416,9 @@ private enum FriendlyOverloadOf
         InterfaceMethod,
     }
 
+    /// <summary>
+    /// Gets a map of interop APIs that should never be generated, whether marshaling is allowed or not, and messages to emit in diagnostics if these APIs are ever directly requested.
+    /// </summary>
     internal static ImmutableDictionary<string, string> BannedAPIsWithoutMarshaling { get; } = ImmutableDictionary<string, string>.Empty
         .Add("GetLastError", "Do not generate GetLastError. Call Marshal.GetLastWin32Error() instead. Learn more from https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.marshal.getlastwin32error")
         .Add("OLD_LARGE_INTEGER", "Use the C# long keyword instead.")
@@ -418,6 +428,9 @@ private enum FriendlyOverloadOf
         .Add("POINT", "Use System.Drawing.Point instead.")
         .Add("POINTF", "Use System.Drawing.PointF instead.");
 
+    /// <summary>
+    /// Gets a map of interop APIs that should not be generated when marshaling is allowed, and messages to emit in diagnostics if these APIs are ever directly requested.
+    /// </summary>
     internal static ImmutableDictionary<string, string> BannedAPIsWithMarshaling { get; } = BannedAPIsWithoutMarshaling
         .Add("VARIANT", "Use `object` instead of VARIANT when in COM interface mode. VARIANT can only be emitted when emitting COM interfaces as structs.");