From 14f4ed2ba3a86bbb2bca77690d036316c3d21fc8 Mon Sep 17 00:00:00 2001
From: Chris Denton <chris@chrisdenton.dev>
Date: Thu, 4 Jul 2024 13:27:24 +0000
Subject: [PATCH] Add comments to windows_targets.rs

---
 library/std/src/sys/pal/windows/c/windows_targets.rs | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/library/std/src/sys/pal/windows/c/windows_targets.rs b/library/std/src/sys/pal/windows/c/windows_targets.rs
index cc3cc6e861194..56c563462d366 100644
--- a/library/std/src/sys/pal/windows/c/windows_targets.rs
+++ b/library/std/src/sys/pal/windows/c/windows_targets.rs
@@ -1,5 +1,14 @@
+//! Provides the `link!` macro used by the generated windows bindings.
+//!
+//! This is a simple wrapper around an `extern` block with a `#[link]` attribute.
+//! It's very roughly equivalent to the windows-targets crate.
+
 pub macro link {
     ($library:literal $abi:literal $($link_name:literal)? $(#[$doc:meta])? fn $($function:tt)*) => (
+        // Note: the windows-targets crate uses a pre-built Windows.lib import library which we don't
+        // have in this repo. So instead we always link kernel32.lib and add the rest of the import
+        // libraries below by using an empty extern block. This works because extern blocks are not
+        // connected to the library given in the #[link] attribute.
         #[link(name = "kernel32")]
         extern $abi {
             $(#[link_name=$link_name])?