From 3e3c87b5ed5d500e87a31fede90fd8d35df60fa9 Mon Sep 17 00:00:00 2001
From: Kenny Kerr <kenny@kennykerr.ca>
Date: Tue, 28 Mar 2023 11:34:10 -0500
Subject: [PATCH] Update readme to include `windows-targets` and
 `windows-bindgen` (#2399)

---
 crates/libs/bindgen/Cargo.toml |  1 +
 crates/libs/bindgen/src/lib.rs | 12 ++++++++-
 crates/libs/targets/Cargo.toml |  1 +
 crates/libs/targets/src/lib.rs |  4 +++
 docs/readme.md                 | 47 ++++++++++++++++++++++++++++++++--
 5 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/crates/libs/bindgen/Cargo.toml b/crates/libs/bindgen/Cargo.toml
index 21c3120803..a1ee8943ec 100644
--- a/crates/libs/bindgen/Cargo.toml
+++ b/crates/libs/bindgen/Cargo.toml
@@ -6,6 +6,7 @@ edition = "2018"
 license = "MIT OR Apache-2.0"
 description = "Code gen support for the windows and windows-sys crates"
 repository = "https://github.com/microsoft/windows-rs"
+readme = "../../../docs/readme.md"
 
 [package.metadata.docs.rs]
 default-target = "x86_64-pc-windows-msvc"
diff --git a/crates/libs/bindgen/src/lib.rs b/crates/libs/bindgen/src/lib.rs
index 06f1e3198e..1c9095e4ba 100644
--- a/crates/libs/bindgen/src/lib.rs
+++ b/crates/libs/bindgen/src/lib.rs
@@ -1,3 +1,7 @@
+/*!
+Learn more about Rust for Windows here: <https://github.com/microsoft/windows-rs>
+*/
+
 mod classes;
 mod com_methods;
 mod constants;
@@ -13,13 +17,16 @@ mod iterators;
 mod method_names;
 mod structs;
 mod winrt_methods;
-pub use gen::*;
 use metadata::reader::*;
 use method_names::*;
 use std::collections::*;
 use std::fmt::Write;
 use tokens::*;
 
+#[doc(hidden)]
+pub use gen::*;
+
+#[doc(hidden)]
 pub fn namespace(gen: &Gen, tree: &Tree) -> String {
     let mut tokens = TokenStream::new();
 
@@ -143,6 +150,7 @@ pub fn namespace(gen: &Gen, tree: &Tree) -> String {
     tokens.into_string()
 }
 
+#[doc(hidden)]
 pub fn namespace_impl(gen: &Gen, tree: &Tree) -> String {
     let mut types = BTreeMap::<&str, TokenStream>::new();
 
@@ -174,6 +182,7 @@ pub fn namespace_impl(gen: &Gen, tree: &Tree) -> String {
     tokens.into_string()
 }
 
+/// Generates bindings for a specific component namespace.
 pub fn component(namespace: &str, files: &[File]) -> String {
     let reader = &Reader::new(files);
     let tree = reader.tree(namespace, &Default::default());
@@ -185,6 +194,7 @@ pub fn component(namespace: &str, files: &[File]) -> String {
     bindings
 }
 
+/// Generates standalone bindings for Windows APIs.
 pub fn standalone(names: &[&str]) -> String {
     let files = &File::with_default(&[]).unwrap();
     let reader = &Reader::new(files);
diff --git a/crates/libs/targets/Cargo.toml b/crates/libs/targets/Cargo.toml
index 509056d882..edb156b074 100644
--- a/crates/libs/targets/Cargo.toml
+++ b/crates/libs/targets/Cargo.toml
@@ -7,6 +7,7 @@ edition = "2018"
 license = "MIT OR Apache-2.0"
 description = "Import libs for Windows"
 repository = "https://github.com/microsoft/windows-rs"
+readme = "../../../docs/readme.md"
 
 [target.i686-pc-windows-msvc.dependencies]
 windows_i686_msvc = { path = "../../targets/i686_msvc", version = "0.42.2" }
diff --git a/crates/libs/targets/src/lib.rs b/crates/libs/targets/src/lib.rs
index 0c9ac1ac8e..e5bd66ae10 100644
--- a/crates/libs/targets/src/lib.rs
+++ b/crates/libs/targets/src/lib.rs
@@ -1 +1,5 @@
+/*!
+Learn more about Rust for Windows here: <https://github.com/microsoft/windows-rs>
+*/
+
 #![no_std]
diff --git a/docs/readme.md b/docs/readme.md
index 06911dec2d..e4e1d537e9 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -20,7 +20,7 @@ features = [
 ]
 ```
 
-Make use of any Windows APIs as needed.
+Make use of any Windows APIs as needed:
 
 ```rust,no_run
 use windows::{
@@ -67,7 +67,7 @@ features = [
 ]
 ```
 
-Make use of any Windows APIs as needed.
+Make use of any Windows APIs as needed:
 
 ```rust,no_run
 use windows_sys::{
@@ -86,3 +86,46 @@ fn main() {
     }
 }
 ```
+
+## windows-bindgen
+
+Even with a [choice between the windows and windows-sys crates](https://kennykerr.ca/rust-getting-started/windows-or-windows-sys.html), some developers may prefer to use completely standalone bindings. The [windows-bindgen](https://crates.io/crates/windows-bindgen) crate lets you generate entirely standalone bindings for Windows APIs with a single function call that you can run from a test to automate the generation of bindings. This can help to reduce your dependencies while continuing to provide a sustainable path forward for any future API requirements you might have, or just to refresh your bindings from time to time to pick up any bug fixes automatically from Microsoft.
+
+Start by adding the following to your Cargo.toml file:
+
+```toml
+[dependencies.windows-targets]
+version = "0.46.0"
+
+[dev-dependencies.windows-bindgen]
+version = "0.46.0"
+```
+
+The `windows-bindgen` crate is only needed for generating bindings and is thus a dev dependency only. The [windows-targets](https://crates.io/crates/windows-targets) crate is a dependency shared by the `windows` and `windows-sys` crates and only contains import libs for supported targets. This will ensure that you can link against any Windows API functions you may need. 
+
+Write a test to generate bindings as follows:
+
+```rust,no_run
+#[test]
+fn gen_bindings() {
+    let apis = [
+        "Windows.Win32.System.SystemInformation.GetTickCount",
+    ];
+
+    let bindings = windows_bindgen::standalone(&apis);
+    std::fs::write("src/bindings.rs", bindings).unwrap();
+}
+```
+
+Make use of any Windows APIs as needed.
+
+```rust,no_run,ignore
+mod bindings;
+use bindings::*;
+
+fn main() {
+    unsafe {
+        println!("{}", GetTickCount());
+    }
+}
+```