From 93b687b70fb0f1450f4e5aefb7e549d546b1cf4b Mon Sep 17 00:00:00 2001 From: Kenny Kerr Date: Wed, 17 Jan 2024 09:22:51 -0600 Subject: [PATCH 1/4] core docs --- crates/libs/core/src/param.rs | 1 + crates/libs/core/src/variant.rs | 10 ++++++++++ 2 files changed, 11 insertions(+) diff --git a/crates/libs/core/src/param.rs b/crates/libs/core/src/param.rs index ea5b400060..8dca3e059c 100644 --- a/crates/libs/core/src/param.rs +++ b/crates/libs/core/src/param.rs @@ -17,6 +17,7 @@ impl> Param { } } +#[doc(hidden)] pub trait CanInto: Sized { const QUERY: bool = false; } diff --git a/crates/libs/core/src/variant.rs b/crates/libs/core/src/variant.rs index e7885ee30a..64db50203b 100644 --- a/crates/libs/core/src/variant.rs +++ b/crates/libs/core/src/variant.rs @@ -1,8 +1,10 @@ use super::*; +/// A VARIANT ([VARIANT](https://learn.microsoft.com/en-us/windows/win32/api/oaidl/ns-oaidl-variant)) is a container that can store different types of values. #[repr(transparent)] pub struct VARIANT(imp::VARIANT); +/// A PROPVARIANT ([PROPVARIANT](https://learn.microsoft.com/en-us/windows/win32/api/propidlbase/ns-propidlbase-propvariant)) is a container that can store different types of values. #[repr(transparent)] pub struct PROPVARIANT(imp::PROPVARIANT); @@ -130,20 +132,28 @@ impl Eq for VARIANT {} impl Eq for PROPVARIANT {} impl VARIANT { + /// Create an empty `VARIANT`. + /// + /// This function does not allocate memory. pub fn new() -> Self { unsafe { std::mem::zeroed() } } + /// Returns true if the `VARIANT` is empty. pub const fn is_empty(&self) -> bool { unsafe { self.0.Anonymous.Anonymous.vt == imp::VT_EMPTY } } } impl PROPVARIANT { + /// Create an empty `PROPVARIANT`. + /// + /// This function does not allocate memory. pub fn new() -> Self { unsafe { std::mem::zeroed() } } + /// Returns true if the `PROPVARIANT` is empty. pub const fn is_empty(&self) -> bool { unsafe { self.0.Anonymous.Anonymous.vt == imp::VT_EMPTY } } From 3bbbc0eb6346a483d83572b3c58c6645e4b6ada6 Mon Sep 17 00:00:00 2001 From: Kenny Kerr Date: Wed, 17 Jan 2024 09:57:50 -0600 Subject: [PATCH 2/4] missing_docs --- Cargo.toml | 1 + crates/libs/bindgen/src/error.rs | 2 ++ crates/libs/bindgen/src/lib.rs | 5 +++++ crates/libs/core/src/guid.rs | 7 +++++++ crates/libs/core/src/interface.rs | 5 +++++ crates/libs/implement/src/lib.rs | 4 ++++ crates/libs/interface/src/lib.rs | 4 ++++ crates/libs/metadata/src/lib.rs | 6 ++++++ crates/libs/targets/src/lib.rs | 4 ++++ crates/libs/version/src/lib.rs | 4 ++++ 10 files changed, 42 insertions(+) diff --git a/Cargo.toml b/Cargo.toml index 92ea139e9c..4cb7f88c48 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -15,3 +15,4 @@ exclude = [ [workspace.lints.rust] rust_2018_idioms = "warn" unused_qualifications = "warn" +missing_docs = "warn" diff --git a/crates/libs/bindgen/src/error.rs b/crates/libs/bindgen/src/error.rs index 16122bbf69..de2bf1d7a3 100644 --- a/crates/libs/bindgen/src/error.rs +++ b/crates/libs/bindgen/src/error.rs @@ -1,5 +1,7 @@ +/// A specialized [`Result`] type that provides compiler error information. pub type Result = std::result::Result; +/// An error object consists of both an error message and file and line information. #[derive(Default, Debug)] pub struct Error { message: String, diff --git a/crates/libs/bindgen/src/lib.rs b/crates/libs/bindgen/src/lib.rs index 91f19df2e1..ea371d34d0 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: +*/ + mod args; mod error; mod metadata; @@ -18,6 +22,7 @@ enum ArgKind { Config, } +/// Windows metadata compiler. pub fn bindgen(args: I) -> Result where I: IntoIterator, diff --git a/crates/libs/core/src/guid.rs b/crates/libs/core/src/guid.rs index 621b34d316..d18e354dec 100644 --- a/crates/libs/core/src/guid.rs +++ b/crates/libs/core/src/guid.rs @@ -7,9 +7,16 @@ use super::*; #[repr(C)] #[derive(Clone, Copy, Default, PartialEq, Eq, Hash)] pub struct GUID { + /// Specifies the first 8 hexadecimal digits. pub data1: u32, + + /// Specifies the first group of 4 hexadecimal digits. pub data2: u16, + + /// Specifies the second group of 4 hexadecimal digits. pub data3: u16, + + /// The first 2 bytes contain the third group of 4 hexadecimal digits. The remaining 6 bytes contain the final 12 hexadecimal digits. pub data4: [u8; 8], } diff --git a/crates/libs/core/src/interface.rs b/crates/libs/core/src/interface.rs index b9b1593d11..9fbe7d7ce9 100644 --- a/crates/libs/core/src/interface.rs +++ b/crates/libs/core/src/interface.rs @@ -7,8 +7,13 @@ use super::*; /// /// # Safety pub unsafe trait Interface: Sized + Clone { + #[doc(hidden)] type Vtable; + + #[doc(hidden)] const IID: GUID; + + #[doc(hidden)] const UNKNOWN: bool = true; /// A reference to the interface's vtable diff --git a/crates/libs/implement/src/lib.rs b/crates/libs/implement/src/lib.rs index 45234a22b7..f1cbeec544 100644 --- a/crates/libs/implement/src/lib.rs +++ b/crates/libs/implement/src/lib.rs @@ -1,3 +1,7 @@ +/*! +Learn more about Rust for Windows here: +*/ + use quote::{quote, ToTokens}; /// Implements one or more COM interfaces. diff --git a/crates/libs/interface/src/lib.rs b/crates/libs/interface/src/lib.rs index 5ca509587f..21f8fbaf5a 100644 --- a/crates/libs/interface/src/lib.rs +++ b/crates/libs/interface/src/lib.rs @@ -1,3 +1,7 @@ +/*! +Learn more about Rust for Windows here: +*/ + use quote::quote; use syn::spanned::Spanned; diff --git a/crates/libs/metadata/src/lib.rs b/crates/libs/metadata/src/lib.rs index 15220b1783..1b3d959cc1 100644 --- a/crates/libs/metadata/src/lib.rs +++ b/crates/libs/metadata/src/lib.rs @@ -1,3 +1,9 @@ +/*! +Learn more about Rust for Windows here: +*/ + +#![doc(hidden)] + use std::cmp::Ordering; use std::collections::*; diff --git a/crates/libs/targets/src/lib.rs b/crates/libs/targets/src/lib.rs index 64ebb503b4..33061f32e2 100644 --- a/crates/libs/targets/src/lib.rs +++ b/crates/libs/targets/src/lib.rs @@ -4,6 +4,7 @@ Learn more about Rust for Windows here: +*/ + #![cfg_attr(not(test), no_std)] mod bindings; From 6c9faed093aa0411f3226fb4f6910874435db9e3 Mon Sep 17 00:00:00 2001 From: Kenny Kerr Date: Wed, 17 Jan 2024 10:11:24 -0600 Subject: [PATCH 3/4] windows-sys has no docs --- crates/libs/sys/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/libs/sys/src/lib.rs b/crates/libs/sys/src/lib.rs index a6ff1fc802..7b801b34ca 100644 --- a/crates/libs/sys/src/lib.rs +++ b/crates/libs/sys/src/lib.rs @@ -4,7 +4,7 @@ Learn more about Rust for Windows here: Date: Wed, 17 Jan 2024 10:14:37 -0600 Subject: [PATCH 4/4] windows docs --- crates/libs/windows/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/libs/windows/src/lib.rs b/crates/libs/windows/src/lib.rs index 5271e586f5..8f40536faf 100644 --- a/crates/libs/windows/src/lib.rs +++ b/crates/libs/windows/src/lib.rs @@ -5,7 +5,7 @@ Learn more about Rust for Windows here: