Minor doc improvements (#1564)

microsoft · Feb 24, 2022 · 031369d · 031369d
1 parent 4ede491
commit 031369d
Show file tree

Hide file tree

Showing 11 changed files with 14 additions and 9 deletions.
diff --git a/crates/libs/windows/src/core/error.rs b/crates/libs/windows/src/core/error.rs
@@ -1,7 +1,7 @@
 use super::*;
 use bindings::*;
 
-/// A WinRT error object consists of both an error code as well as detailed error information for debugging.
+/// An error object consists of both an error code as well as detailed error information for debugging.
 #[derive(Clone, PartialEq)]
 pub struct Error {
     code: HRESULT,

diff --git a/crates/libs/windows/src/core/guid.rs b/crates/libs/windows/src/core/guid.rs
@@ -3,7 +3,7 @@
 use super::*;
 use bindings::*;
 
-/// A globally unique identifier [(GUID)](https://docs.microsoft.com/en-us/windows/win32/api/guiddef/ns-guiddef-guid)
+/// A globally unique identifier ([GUID](https://docs.microsoft.com/en-us/windows/win32/api/guiddef/ns-guiddef-guid))
 /// used to identify COM and WinRT interfaces.
 #[repr(C)]
 // TODO: write these out

diff --git a/crates/libs/windows/src/core/hresult.rs b/crates/libs/windows/src/core/hresult.rs
@@ -1,7 +1,7 @@
 use super::*;
 use bindings::*;
 
-/// A primitive error code value returned by most COM functions.
+/// An error code value returned by most COM functions.
 #[repr(transparent)]
 #[derive(Copy, Clone, Default, Debug, Eq, PartialEq)]
 #[must_use]

diff --git a/crates/libs/windows/src/core/hstring.rs b/crates/libs/windows/src/core/hstring.rs
@@ -1,9 +1,7 @@
 use super::*;
 
-// TODO: move to HSTRING generated code?
-
-/// A WinRT string, sometimes called an [HSTRING](https://docs.microsoft.com/en-us/windows/win32/winrt/hstring),
-/// is reference-counted and logically immutable. It should only be used for communicating with WinRT APIs.
+/// A WinRT string ([HSTRING](https://docs.microsoft.com/en-us/windows/win32/winrt/hstring)),
+/// is reference-counted and immutable.
 #[repr(transparent)]
 pub struct HSTRING(*mut Header);
 

diff --git a/crates/libs/windows/src/core/inspectable.rs b/crates/libs/windows/src/core/inspectable.rs
@@ -20,6 +20,7 @@ impl IInspectable {
     }
 }
 
+#[doc(hidden)]
 #[repr(C)]
 pub struct IInspectableVtbl {
     pub base: IUnknownVtbl,

diff --git a/crates/libs/windows/src/core/mod.rs b/crates/libs/windows/src/core/mod.rs
@@ -46,7 +46,6 @@ pub use guid::*;
 pub use heap::*;
 pub use hresult::*;
 pub use hstring::*;
-#[doc(hidden)]
 pub use inspectable::*;
 #[doc(hidden)]
 pub use interface::*;
@@ -76,7 +75,7 @@ pub use weak::*;
 #[doc(hidden)]
 pub use weak_ref_count::*;
 
-// A [`Result`] type that provides Windows error information.
+/// A specialized [`Result`] type that provides Windows error information.
 #[must_use]
 pub type Result<T> = core::result::Result<T, Error>;
 
@@ -87,9 +86,11 @@ pub use bindings::IAgileObject;
 #[doc(hidden)]
 pub type RawPtr = *mut core::ffi::c_void;
 
+#[doc(hidden)]
 #[cfg(feature = "implement")]
 pub use windows_implement::implement;
 
+#[doc(hidden)]
 #[cfg(feature = "interface")]
 pub use windows_interface::interface;
 

diff --git a/crates/libs/windows/src/core/pcstr.rs b/crates/libs/windows/src/core/pcstr.rs
@@ -1,5 +1,6 @@
 use super::*;
 
+/// A pointer to a constant null-terminated string of 8-bit Windows (ANSI) characters.
 #[repr(transparent)]
 pub struct PCSTR(pub *const u8);
 impl PCSTR {

diff --git a/crates/libs/windows/src/core/pcwstr.rs b/crates/libs/windows/src/core/pcwstr.rs
@@ -1,5 +1,6 @@
 use super::*;
 
+/// A pointer to a constant null-terminated string of 16-bit Unicode characters.
 #[repr(transparent)]
 pub struct PCWSTR(pub *const u16);
 impl PCWSTR {

diff --git a/crates/libs/windows/src/core/pstr.rs b/crates/libs/windows/src/core/pstr.rs
@@ -1,5 +1,6 @@
 use super::*;
 
+/// A pointer to a null-terminated string of 8-bit Windows (ANSI) characters.
 #[repr(transparent)]
 pub struct PSTR(pub *mut u8);
 impl PSTR {

diff --git a/crates/libs/windows/src/core/pwstr.rs b/crates/libs/windows/src/core/pwstr.rs
@@ -1,5 +1,6 @@
 use super::*;
 
+/// A pointer to a null-terminated string of 16-bit Unicode characters.
 #[repr(transparent)]
 pub struct PWSTR(pub *mut u16);
 impl PWSTR {

diff --git a/crates/libs/windows/src/core/unknown.rs b/crates/libs/windows/src/core/unknown.rs
@@ -57,6 +57,7 @@ impl core::fmt::Debug for IUnknown {
     }
 }
 
+#[doc(hidden)]
 pub trait IUnknownImpl {
     fn get_impl(&mut self) -> RawPtr;