Update readme to include windows-targets and windows-bindgen (#2399)

Author: kennykerr

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"

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);

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" }

crates/libs/targets/src/lib.rs

@@ -1 +1,5 @@
+/*!
+Learn more about Rust for Windows here: <https://github.com/microsoft/windows-rs>
+*/
+
 #![no_std]

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());
+    }
+}
+```